Merge pull request #2420 from return42/fix-sphinx-book-targets

fix makefile `books/{name}.*` targets and add documentation about these targets
This commit is contained in:
Alexandre Flament 2020-12-27 09:47:49 +01:00 committed by GitHub
commit 1ba53e6129
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 42 additions and 8 deletions

View file

@ -150,6 +150,35 @@ Documentation <contrib docs>` section. If you want to edit the documentation
read our :ref:`make docs-live` section. If you are working in your own brand, read our :ref:`make docs-live` section. If you are working in your own brand,
adjust your :ref:`Makefile setup <makefile setup>`. adjust your :ref:`Makefile setup <makefile setup>`.
.. _make books:
``make books/{name}.html books/{name}.pdf``
===========================================
.. _intersphinx: https://www.sphinx-doc.org/en/stable/ext/intersphinx.html
.. _XeTeX: https://tug.org/xetex/
.. sidebar:: info
To build PDF a XeTeX_ is needed, see :ref:`buildhosts`.
The ``books/{name}.*`` targets are building *books*. A *book* is a
sub-directory containing a ``conf.py`` file. One example is the user handbook
which can deployed separately (:origin:`docs/user/conf.py`). Such ``conf.py``
do inherit from :origin:`docs/conf.py` and overwrite values to fit *book's*
needs.
With the help of Intersphinx_ (:ref:`reST smart ref`) the links to searxs
documentation outside of the book will be bound by the object inventory of
``DOCS_URL``. Take into account that URLs will be picked from the inventary at
documentation's build time.
Use ``make docs-help`` to see which books available:
.. program-output:: bash -c "cd ..; make --no-print-directory docs-help"
:ellipsis: 0,-6
.. _make gh-pages: .. _make gh-pages:

View file

@ -319,6 +319,9 @@ To list all anchors of the inventory (e.g. ``python``) use:
.. code:: sh .. code:: sh
$ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
...
$ python -m sphinx.ext.intersphinx https://searx.github.io/searx/objects.inv
...
Literal blocks Literal blocks
============== ==============

View file

@ -4,6 +4,8 @@
project = 'Searx User-HB' project = 'Searx User-HB'
version = release = VERSION_STRING version = release = VERSION_STRING
intersphinx_mapping['searx'] = (DOCS_URL, None)
# Grouping the document tree into LaTeX files. List of tuples # Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, # (source start file, target name, title,
# author, documentclass [howto, manual, or own class]). # author, documentclass [howto, manual, or own class]).

View file

@ -56,9 +56,9 @@ results.
I see. What about private instances? I see. What about private instances?
------------------------------------ ------------------------------------
If users run their own instances, everything is in their control: the source If users run their :ref:`own instances <installation>`, everything is in their
code, logging settings and private data. Unknown instance administrators do not control: the source code, logging settings and private data. Unknown instance
have to be trusted. administrators do not have to be trusted.
Furthermore, as the default settings of their instance is editable, there is no Furthermore, as the default settings of their instance is editable, there is no
need to use cookies to tailor searx to their needs. So preferences will not be need to use cookies to tailor searx to their needs. So preferences will not be

View file

@ -27,7 +27,7 @@ docs-help:
@echo ' docs-clean - clean intermediate doc objects' @echo ' docs-clean - clean intermediate doc objects'
@echo ' $(GH_PAGES) - create & upload github pages' @echo ' $(GH_PAGES) - create & upload github pages'
@echo ' sphinx-pdf - run sphinx latex & pdf targets' @echo ' sphinx-pdf - run sphinx latex & pdf targets'
echo '' @echo ''
@echo ' books/{name}.html : build only the HTML of document {name}' @echo ' books/{name}.html : build only the HTML of document {name}'
@echo ' valid values for books/{name}.html are:' @echo ' valid values for books/{name}.html are:'
@echo ' $(BOOKS_HTML)' | $(FMT) @echo ' $(BOOKS_HTML)' | $(FMT)
@ -99,7 +99,7 @@ sphinx-pdf: sphinx-latex
@echo "SPHINX *.pdf --> file://$(abspath $(DOCS_DIST)/pdf)" @echo "SPHINX *.pdf --> file://$(abspath $(DOCS_DIST)/pdf)"
PHONY += sphinx-latex PHONY += sphinx-latex
sphinx-latex: texlive sphinx-doc sphinx-latex: pyenvinstall texlive
$(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
-b latex \ -b latex \
-c $(DOCS_FOLDER) \ -c $(DOCS_FOLDER) \
@ -124,7 +124,7 @@ $(BOOKS_DIST):
mkdir -p $(BOOKS_DIST) mkdir -p $(BOOKS_DIST)
PHONY += $(BOOKS_HTML) PHONY += $(BOOKS_HTML)
$(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST) $(BOOKS_HTML): pyenvinstall | $(BOOKS_DIST)
SPHINX_CONF=$(patsubst books/%.html,%,$@)/conf.py \ SPHINX_CONF=$(patsubst books/%.html,%,$@)/conf.py \
$(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
-b html \ -b html \
@ -135,7 +135,7 @@ $(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST)
@echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))" @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))"
PHONY += $(BOOKS_HTML) PHONY += $(BOOKS_HTML)
$(BOOKS_LIVE): sphinx-live | $(BOOKS_DIST) $(BOOKS_LIVE): pyenvinstall | $(BOOKS_DIST)
PATH="$(PY_ENV_BIN):$(PATH)" \ PATH="$(PY_ENV_BIN):$(PATH)" \
SPHINX_CONF=$(patsubst books/%.live,%,$@)/conf.py \ SPHINX_CONF=$(patsubst books/%.live,%,$@)/conf.py \
$(PY_ENV_BIN)/sphinx-autobuild --poll -B --host 0.0.0.0 --port 8080 $(SPHINX_VERBOSE) $(SPHINXOPTS)\ $(PY_ENV_BIN)/sphinx-autobuild --poll -B --host 0.0.0.0 --port 8080 $(SPHINX_VERBOSE) $(SPHINXOPTS)\
@ -152,7 +152,7 @@ $(BOOKS_PDF): %.pdf : %.latex
@echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@))/pdf" @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@))/pdf"
PHONY += $(BOOKS_LATEX) PHONY += $(BOOKS_LATEX)
$(BOOKS_LATEX): sphinx-doc | $(BOOKS_DIST) $(BOOKS_LATEX): pyenvinstall | $(BOOKS_DIST)
SPHINX_CONF=$(patsubst books/%.latex,%,$@)/conf.py \ SPHINX_CONF=$(patsubst books/%.latex,%,$@)/conf.py \
$(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
-b latex \ -b latex \