From aace837665aeb30ff1e9c2895ffc92465341b97a Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 24 Dec 2020 13:54:07 +0100 Subject: [PATCH 1/2] [fix] makefile.sphinx: additions to commit c2a6f145 In commit c2a6f145 the sphinx-doc and sphinx-live targets has been removed, since Sphinx is already installed by the pyenvinstall target. This commit removes the targets from the remaining prerequisites of the 'BOOK' targets Signed-off-by: Markus Heiser --- utils/makefile.sphinx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/utils/makefile.sphinx b/utils/makefile.sphinx index b4f298d50..e73686466 100644 --- a/utils/makefile.sphinx +++ b/utils/makefile.sphinx @@ -27,7 +27,7 @@ docs-help: @echo ' docs-clean - clean intermediate doc objects' @echo ' $(GH_PAGES) - create & upload github pages' @echo ' sphinx-pdf - run sphinx latex & pdf targets' - echo '' + @echo '' @echo ' books/{name}.html : build only the HTML of document {name}' @echo ' valid values for books/{name}.html are:' @echo ' $(BOOKS_HTML)' | $(FMT) @@ -99,7 +99,7 @@ sphinx-pdf: sphinx-latex @echo "SPHINX *.pdf --> file://$(abspath $(DOCS_DIST)/pdf)" PHONY += sphinx-latex -sphinx-latex: texlive sphinx-doc +sphinx-latex: pyenvinstall texlive $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ -b latex \ -c $(DOCS_FOLDER) \ @@ -124,7 +124,7 @@ $(BOOKS_DIST): mkdir -p $(BOOKS_DIST) PHONY += $(BOOKS_HTML) -$(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST) +$(BOOKS_HTML): pyenvinstall | $(BOOKS_DIST) SPHINX_CONF=$(patsubst books/%.html,%,$@)/conf.py \ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ -b html \ @@ -135,7 +135,7 @@ $(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST) @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))" PHONY += $(BOOKS_HTML) -$(BOOKS_LIVE): sphinx-live | $(BOOKS_DIST) +$(BOOKS_LIVE): pyenvinstall | $(BOOKS_DIST) PATH="$(PY_ENV_BIN):$(PATH)" \ SPHINX_CONF=$(patsubst books/%.live,%,$@)/conf.py \ $(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" PHONY += $(BOOKS_LATEX) -$(BOOKS_LATEX): sphinx-doc | $(BOOKS_DIST) +$(BOOKS_LATEX): pyenvinstall | $(BOOKS_DIST) SPHINX_CONF=$(patsubst books/%.latex,%,$@)/conf.py \ $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\ -b latex \ From 3beede7ab7c3d1c958d5916496603695664bc50e Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 24 Dec 2020 13:55:22 +0100 Subject: [PATCH 2/2] [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 +++ docs/user/conf.py | 2 ++ docs/user/own-instance.rst | 6 +++--- 4 files changed, 37 insertions(+), 3 deletions(-) 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 ============== diff --git a/docs/user/conf.py b/docs/user/conf.py index 53ade4b63..da2e27533 100644 --- a/docs/user/conf.py +++ b/docs/user/conf.py @@ -4,6 +4,8 @@ project = 'Searx User-HB' version = release = VERSION_STRING +intersphinx_mapping['searx'] = (DOCS_URL, None) + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). diff --git a/docs/user/own-instance.rst b/docs/user/own-instance.rst index af415b61d..bb4c5d524 100644 --- a/docs/user/own-instance.rst +++ b/docs/user/own-instance.rst @@ -56,9 +56,9 @@ results. I see. What about private instances? ------------------------------------ -If users run their own instances, everything is in their control: the source -code, logging settings and private data. Unknown instance administrators do not -have to be trusted. +If users run their :ref:`own instances `, everything is in their +control: the source code, logging settings and private data. Unknown instance +administrators do not have to be trusted. 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