git.iko.soy/searx
on master help sign in
[doc] describe 'make books/{name}.html' and 'books/{name}.pdf'
3beede7Markus Heiser
docs/dev/makefile.rst+29
compare with master
unifiedsplit
@@ -150,6 +150,35 @@ Documentation <contrib docs>` section. If you want to edit the documentation
150read our :ref:`make docs-live` section. If you are working in your own brand,
150read our :ref:`make docs-live` section. If you are working in your own brand,
151adjust your :ref:`Makefile setup <makefile setup>`.
151adjust your :ref:`Makefile setup <makefile setup>`.
152
152
153+.. _make books:
154+
155+``make books/{name}.html books/{name}.pdf``
156+===========================================
157+
158+.. _intersphinx: https://www.sphinx-doc.org/en/stable/ext/intersphinx.html
159+.. _XeTeX: https://tug.org/xetex/
160+
161+.. sidebar:: info
162+
163+ To build PDF a XeTeX_ is needed, see :ref:`buildhosts`.
164+
165+
166+The ``books/{name}.*`` targets are building *books*. A *book* is a
167+sub-directory containing a ``conf.py`` file. One example is the user handbook
168+which can deployed separately (:origin:`docs/user/conf.py`). Such ``conf.py``
169+do inherit from :origin:`docs/conf.py` and overwrite values to fit *book's*
170+needs.
171+
172+With the help of Intersphinx_ (:ref:`reST smart ref`) the links to searx’s
173+documentation outside of the book will be bound by the object inventory of
174+``DOCS_URL``. Take into account that URLs will be picked from the inventary at
175+documentation's build time.
176+
177+Use ``make docs-help`` to see which books available:
178+
179+.. program-output:: bash -c "cd ..; make --no-print-directory docs-help"
180+ :ellipsis: 0,-6
181+
153
182
154.. _make gh-pages:
183.. _make gh-pages:
155
184
docs/dev/reST.rst+3
@@ -319,6 +319,9 @@ To list all anchors of the inventory (e.g. ``python``) use:
319.. code:: sh
319.. code:: sh
320
320
321 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
321 $ python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv
322+ ...
323+ $ python -m sphinx.ext.intersphinx https://searx.github.io/searx/objects.inv
324+ ...
322
325
323Literal blocks
326Literal blocks
324==============
327==============
docs/user/conf.py+2
@@ -4,6 +4,8 @@
4project = 'Searx User-HB'
4project = 'Searx User-HB'
5version = release = VERSION_STRING
5version = release = VERSION_STRING
6
6
7+intersphinx_mapping['searx'] = (DOCS_URL, None)
8+
7# Grouping the document tree into LaTeX files. List of tuples
9# Grouping the document tree into LaTeX files. List of tuples
8# (source start file, target name, title,
10# (source start file, target name, title,
9# author, documentclass [howto, manual, or own class]).
11# author, documentclass [howto, manual, or own class]).
docs/user/own-instance.rst+3−3
@@ -56,9 +56,9 @@ results.
56I see. What about private instances?
56I see. What about private instances?
57------------------------------------
57------------------------------------
58
58
59−If users run their own instances, everything is in their control: the source
59+If users run their :ref:`own instances <installation>`, everything is in their
60−code, logging settings and private data. Unknown instance administrators do not
60+control: the source code, logging settings and private data. Unknown instance
61−have to be trusted.
61+administrators do not have to be trusted.
62
62
63Furthermore, as the default settings of their instance is editable, there is no
63Furthermore, as the default settings of their instance is editable, there is no
64need to use cookies to tailor searx to their needs. So preferences will not be
64need to use cookies to tailor searx to their needs. So preferences will not be