git.iko.soy/searx
on master help sign in
Merge pull request #2420 from return42/fix-sphinx-book-targets

fix makefile `books/{name}.*` targets and add documentation about these targets

commit1ba53e6129f70d31f1af72993ce131de7f21e653 authorAlexandre Flament <alex@al-f.net> dateSun 27 Dec 2020, 09:47 (6 years ago) parent1956ab43beede7
5 files changed+42−8
compare with master
unifiedsplit
docs/dev/makefile.rst+29 docs/dev/reST.rst+3 docs/user/conf.py+2 docs/user/own-instance.rst+3−3 utils/makefile.sphinx+5−5
docs/dev/makefile.rst+29
@@ -150,6 +150,35 @@ Documentation <contrib docs>` section. If you want to edit the documentation
150150read our :ref:`make docs-live` section. If you are working in your own brand,
151151adjust your :ref:`Makefile setup <makefile setup>`.
152152
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+
153182
154183.. _make gh-pages:
155184
docs/dev/reST.rst+3
@@ -319,6 +319,9 @@ To list all anchors of the inventory (e.g. ``python``) use:
319319.. code:: sh
320320
321321 $ 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+ ...
322325
323326Literal blocks
324327==============
docs/user/conf.py+2
@@ -4,6 +4,8 @@
44project = 'Searx User-HB'
55version = release = VERSION_STRING
66
7+intersphinx_mapping['searx'] = (DOCS_URL, None)
8+
79# Grouping the document tree into LaTeX files. List of tuples
810# (source start file, target name, title,
911# author, documentclass [howto, manual, or own class]).
docs/user/own-instance.rst+3−3
@@ -56,9 +56,9 @@ results.
5656I see. What about private instances?
5757------------------------------------
5858
59−If users run their own instances, everything is in their control: the source
60−code, logging settings and private data. Unknown instance administrators do not
61−have to be trusted.
59+If users run their :ref:`own instances <installation>`, everything is in their
60+control: the source code, logging settings and private data. Unknown instance
61+administrators do not have to be trusted.
6262
6363Furthermore, as the default settings of their instance is editable, there is no
6464need to use cookies to tailor searx to their needs. So preferences will not be
utils/makefile.sphinx+5−5
@@ -27,7 +27,7 @@ docs-help:
2727 @echo ' docs-clean - clean intermediate doc objects'
2828 @echo ' $(GH_PAGES) - create & upload github pages'
2929 @echo ' sphinx-pdf - run sphinx latex & pdf targets'
30− echo ''
30+ @echo ''
3131 @echo ' books/{name}.html : build only the HTML of document {name}'
3232 @echo ' valid values for books/{name}.html are:'
3333 @echo ' $(BOOKS_HTML)' | $(FMT)
@@ -99,7 +99,7 @@ sphinx-pdf: sphinx-latex
9999 @echo "SPHINX *.pdf --> file://$(abspath $(DOCS_DIST)/pdf)"
100100
101101PHONY += sphinx-latex
102−sphinx-latex: texlive sphinx-doc
102+sphinx-latex: pyenvinstall texlive
103103 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
104104 -b latex \
105105 -c $(DOCS_FOLDER) \
@@ -124,7 +124,7 @@ $(BOOKS_DIST):
124124 mkdir -p $(BOOKS_DIST)
125125
126126PHONY += $(BOOKS_HTML)
127−$(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST)
127+$(BOOKS_HTML): pyenvinstall | $(BOOKS_DIST)
128128 SPHINX_CONF=$(patsubst books/%.html,%,$@)/conf.py \
129129 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
130130 -b html \
@@ -135,7 +135,7 @@ $(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST)
135135 @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))"
136136
137137PHONY += $(BOOKS_HTML)
138−$(BOOKS_LIVE): sphinx-live | $(BOOKS_DIST)
138+$(BOOKS_LIVE): pyenvinstall | $(BOOKS_DIST)
139139 PATH="$(PY_ENV_BIN):$(PATH)" \
140140 SPHINX_CONF=$(patsubst books/%.live,%,$@)/conf.py \
141141 $(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
152152 @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@))/pdf"
153153
154154PHONY += $(BOOKS_LATEX)
155−$(BOOKS_LATEX): sphinx-doc | $(BOOKS_DIST)
155+$(BOOKS_LATEX): pyenvinstall | $(BOOKS_DIST)
156156 SPHINX_CONF=$(patsubst books/%.latex,%,$@)/conf.py \
157157 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
158158 -b latex \