Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Unverified Commit 1ba53e61 authored by Alexandre Flament's avatar Alexandre Flament Committed by GitHub
Browse files

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

fix makefile `books/{name}.*` targets and add documentation about these targets
parents 1956ab4b 3beede7a

docs/dev/makefile.rst

+29 −0
Original line number Diff line number Diff line
@@ -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,

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 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:

docs/dev/reST.rst

+3 −0
Original line number Diff line number Diff line
@@ -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

==============

docs/user/conf.py

+2 −0
Original line number Diff line number Diff line
@@ -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]).

docs/user/own-instance.rst

+3 −3
Original line number Diff line number Diff line
@@ -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 <installation>`, 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

utils/makefile.sphinx

+5 −5
Original line number Diff line number Diff line
@@ -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 \