git.iko.soy/searx
on master help sign in
docs: building (PDF) books / build user book

BTW: cleaned up Makefile target help Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

commit2d956696e94e5639db6e12648442989919c48c22 authorMarkus Heiser <markus.heiser@darmarit.de> dateSat 21 Mar 2020, 18:45 (7 years ago) parentd2cfe9c
5 files changed+90−7
compare with master
unifiedsplit
Makefile+13−4 docs/conf.py+7 docs/user/conf.py+19 utils/makefile.sphinx+3−3 utils/site-python/sphinx_build_tools.py+48
Makefile+13−4
@@ -12,8 +12,13 @@ include utils/makefile.sphinx
1212
1313all: clean install
1414
15−PHONY += help
16−help:
15+PHONY += help-min help-all help
16+
17+help: help-min
18+ @echo ''
19+ @echo 'to get more help: make help-all'
20+
21+help-min:
1722 @echo ' test - run developer tests'
1823 @echo ' docs - build documentation'
1924 @echo ' docs-live - autobuild HTML documentation while editing'
@@ -29,9 +34,13 @@ help:
2934 @echo ' GIT_URL = $(GIT_URL)'
3035 @echo ' DOCS_URL = $(DOCS_URL)'
3136 @echo ''
32− @$(MAKE) -e -s -f utils/makefile.include make-help
37+ @$(MAKE) -e -s make-help
38+
39+help-all: help-min
40+ @echo ''
41+ @$(MAKE) -e -s python-help
3342 @echo ''
34− @$(MAKE) -e -s -f utils/makefile.python python-help
43+ @$(MAKE) -e -s docs-help
3544
3645PHONY += install
3746install: pyenvinstall
docs/conf.py+7
@@ -1,6 +1,7 @@
11# -*- coding: utf-8 -*-
22
33import sys, os
4+from sphinx_build_tools import load_sphinx_config
45from searx.version import VERSION_STRING
56from pallets_sphinx_themes import ProjectLink
67
@@ -116,3 +117,9 @@ html_show_sourcelink = False
116117latex_documents = [
117118 (master_doc, "searx-{}.tex".format(VERSION_STRING), html_title, author, "manual")
118119]
120+
121+# ------------------------------------------------------------------------------
122+# Since loadConfig overwrites settings from the global namespace, it has to be
123+# the last statement in the conf.py file
124+# ------------------------------------------------------------------------------
125+load_sphinx_config(globals())
docs/user/conf.pynew file+19
@@ -0,0 +1,19 @@
1+# -*- coding: utf-8; mode: python -*-
2+"""Configuration for the CDB 15 Infrastruktur book
3+"""
4+project = 'Searx User-HB'
5+version = release = VERSION_STRING
6+
7+# Grouping the document tree into LaTeX files. List of tuples
8+# (source start file, target name, title,
9+# author, documentclass [howto, manual, or own class]).
10+latex_documents = [
11+ ('index' # startdocname
12+ , 'searx-user-hb.tex' # targetname
13+ , '' # take title from .rst
14+ , author # author
15+ , 'howto' # documentclass
16+ , False # toctree_only
17+ ),
18+]
19+
utils/makefile.sphinx+3−3
@@ -156,7 +156,7 @@ $(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST)
156156 -b html \
157157 -c $(DOCS_FOLDER) \
158158 -d $(DOCS_BUILD)/books/$(patsubst books/%.html,%,$@)/.doctrees \
159− $(patsubst books/%.html,%,$@) \
159+ $(BOOKS_FOLDER)/$(patsubst books/%.html,%,$@) \
160160 $(BOOKS_DIST)/$(patsubst books/%.html,%,$@)
161161 @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))"
162162
@@ -168,7 +168,7 @@ $(BOOKS_LIVE): sphinx-live | $(BOOKS_DIST)
168168 -b html \
169169 -c $(DOCS_FOLDER) \
170170 -d $(DOCS_BUILD)/books/$(patsubst books/%.live,%,$@)/.doctrees \
171− $(patsubst books/%.live,%,$@) \
171+ $(BOOKS_FOLDER)/$(patsubst books/%.live,%,$@) \
172172 $(BOOKS_DIST)/$(patsubst books/%.live,%,$@)
173173
174174$(BOOKS_PDF): %.pdf : %.latex
@@ -184,7 +184,7 @@ $(BOOKS_LATEX): sphinx-doc | $(BOOKS_DIST)
184184 -b latex \
185185 -c $(DOCS_FOLDER) \
186186 -d $(DOCS_BUILD)/books/$(patsubst books/%.latex,%,$@)/.doctrees \
187− $(patsubst books/%.latex,%,$@) \
187+ $(BOOKS_FOLDER)/$(patsubst books/%.latex,%,$@) \
188188 $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@)
189189 @echo "SPHINX $@ --> file://$(abspath $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@))"
190190
utils/site-python/sphinx_build_tools.pynew file+48
@@ -0,0 +1,48 @@
1+# -*- coding: utf-8; mode: python -*-
2+"""Implement some sphinx-build tools.
3+
4+"""
5+
6+import os
7+import sys
8+from sphinx.util.pycompat import execfile_
9+
10+# ------------------------------------------------------------------------------
11+def load_sphinx_config(namespace):
12+# ------------------------------------------------------------------------------
13+
14+ u"""Load an additional configuration file into *namespace*.
15+
16+ The name of the configuration file is taken from the environment
17+ ``SPHINX_CONF``. The external configuration file extends (or overwrites) the
18+ configuration values from the origin ``conf.py``. With this you are able to
19+ maintain *build themes*. To your docs/conf.py add::
20+
21+ from sphinx_build_tools import load_sphinx_config
22+ ...
23+
24+ # Since loadConfig overwrites settings from the global namespace, it has to be
25+ # the last statement in the conf.py file
26+
27+ load_sphinx_config(globals())
28+
29+ """
30+
31+ config_file = os.environ.get("SPHINX_CONF", None)
32+ if (config_file is not None
33+ and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ):
34+ config_file = os.path.abspath(config_file)
35+
36+ if os.path.isfile(config_file):
37+ sys.stdout.write(
38+ "load additional sphinx-config: %s\n"
39+ % config_file)
40+ config = namespace.copy()
41+ config['__file__'] = config_file
42+ execfile_(config_file, config)
43+ del config['__file__']
44+ namespace.update(config)
45+ else:
46+ sys.stderr.write(
47+ "WARNING: additional sphinx-config not found: %s\n"
48+ % config_file)