From 3beede7ab7c3d1c958d5916496603695664bc50e Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 24 Dec 2020 13:55:22 +0100 Subject: [doc] describe 'make books/{name}.html' and 'books/{name}.pdf' Signed-off-by: Markus Heiser --- docs/dev/makefile.rst | 29 +++++++++++++++++++++++++++++ docs/dev/reST.rst | 3 +++ 2 files changed, 32 insertions(+) (limited to 'docs/dev') diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst index 699729a28..c43855617 100644 --- a/docs/dev/makefile.rst +++ b/docs/dev/makefile.rst @@ -150,6 +150,35 @@ Documentation ` section. If you want to edit the documentation read our :ref:`make docs-live` section. If you are working in your own brand, adjust your :ref:`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 searx’s +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: diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 963378748..8adf4115e 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -319,6 +319,9 @@ To list all anchors of the inventory (e.g. ``python``) use: .. code:: sh $ 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 ============== -- cgit v1.2.3-54-g00ecf