From 2d956696e94e5639db6e12648442989919c48c22 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 21 Mar 2020 18:45:38 +0100 Subject: [PATCH] docs: building (PDF) books / build user book BTW: cleaned up Makefile target help Signed-off-by: Markus Heiser --- Makefile | 17 ++++++--- docs/conf.py | 7 ++++ docs/user/conf.py | 19 ++++++++++ utils/makefile.sphinx | 6 ++-- utils/site-python/sphinx_build_tools.py | 48 +++++++++++++++++++++++++ 5 files changed, 90 insertions(+), 7 deletions(-) create mode 100644 docs/user/conf.py create mode 100644 utils/site-python/sphinx_build_tools.py diff --git a/Makefile b/Makefile index d46c96a4..84f0ac24 100644 --- a/Makefile +++ b/Makefile @@ -12,8 +12,13 @@ include utils/makefile.sphinx all: clean install -PHONY += help -help: +PHONY += help-min help-all help + +help: help-min + @echo '' + @echo 'to get more help: make help-all' + +help-min: @echo ' test - run developer tests' @echo ' docs - build documentation' @echo ' docs-live - autobuild HTML documentation while editing' @@ -29,9 +34,13 @@ help: @echo ' GIT_URL = $(GIT_URL)' @echo ' DOCS_URL = $(DOCS_URL)' @echo '' - @$(MAKE) -e -s -f utils/makefile.include make-help + @$(MAKE) -e -s make-help + +help-all: help-min @echo '' - @$(MAKE) -e -s -f utils/makefile.python python-help + @$(MAKE) -e -s python-help + @echo '' + @$(MAKE) -e -s docs-help PHONY += install install: pyenvinstall diff --git a/docs/conf.py b/docs/conf.py index 6a663334..c2b2bbd8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,7 @@ # -*- coding: utf-8 -*- import sys, os +from sphinx_build_tools import load_sphinx_config from searx.version import VERSION_STRING from pallets_sphinx_themes import ProjectLink @@ -116,3 +117,9 @@ html_show_sourcelink = False latex_documents = [ (master_doc, "searx-{}.tex".format(VERSION_STRING), html_title, author, "manual") ] + +# ------------------------------------------------------------------------------ +# Since loadConfig overwrites settings from the global namespace, it has to be +# the last statement in the conf.py file +# ------------------------------------------------------------------------------ +load_sphinx_config(globals()) diff --git a/docs/user/conf.py b/docs/user/conf.py new file mode 100644 index 00000000..d4bdb576 --- /dev/null +++ b/docs/user/conf.py @@ -0,0 +1,19 @@ +# -*- coding: utf-8; mode: python -*- +"""Configuration for the CDB 15 Infrastruktur book +""" +project = 'Searx User-HB' +version = release = VERSION_STRING + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index' # startdocname + , 'searx-user-hb.tex' # targetname + , '' # take title from .rst + , author # author + , 'howto' # documentclass + , False # toctree_only + ), +] + diff --git a/utils/makefile.sphinx b/utils/makefile.sphinx index 4926bb53..8a1f6b76 100644 --- a/utils/makefile.sphinx +++ b/utils/makefile.sphinx @@ -156,7 +156,7 @@ $(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST) -b html \ -c $(DOCS_FOLDER) \ -d $(DOCS_BUILD)/books/$(patsubst books/%.html,%,$@)/.doctrees \ - $(patsubst books/%.html,%,$@) \ + $(BOOKS_FOLDER)/$(patsubst books/%.html,%,$@) \ $(BOOKS_DIST)/$(patsubst books/%.html,%,$@) @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))" @@ -168,7 +168,7 @@ $(BOOKS_LIVE): sphinx-live | $(BOOKS_DIST) -b html \ -c $(DOCS_FOLDER) \ -d $(DOCS_BUILD)/books/$(patsubst books/%.live,%,$@)/.doctrees \ - $(patsubst books/%.live,%,$@) \ + $(BOOKS_FOLDER)/$(patsubst books/%.live,%,$@) \ $(BOOKS_DIST)/$(patsubst books/%.live,%,$@) $(BOOKS_PDF): %.pdf : %.latex @@ -184,7 +184,7 @@ $(BOOKS_LATEX): sphinx-doc | $(BOOKS_DIST) -b latex \ -c $(DOCS_FOLDER) \ -d $(DOCS_BUILD)/books/$(patsubst books/%.latex,%,$@)/.doctrees \ - $(patsubst books/%.latex,%,$@) \ + $(BOOKS_FOLDER)/$(patsubst books/%.latex,%,$@) \ $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@) @echo "SPHINX $@ --> file://$(abspath $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@))" diff --git a/utils/site-python/sphinx_build_tools.py b/utils/site-python/sphinx_build_tools.py new file mode 100644 index 00000000..b9ebdeac --- /dev/null +++ b/utils/site-python/sphinx_build_tools.py @@ -0,0 +1,48 @@ +# -*- coding: utf-8; mode: python -*- +"""Implement some sphinx-build tools. + +""" + +import os +import sys +from sphinx.util.pycompat import execfile_ + +# ------------------------------------------------------------------------------ +def load_sphinx_config(namespace): +# ------------------------------------------------------------------------------ + + u"""Load an additional configuration file into *namespace*. + + The name of the configuration file is taken from the environment + ``SPHINX_CONF``. The external configuration file extends (or overwrites) the + configuration values from the origin ``conf.py``. With this you are able to + maintain *build themes*. To your docs/conf.py add:: + + from sphinx_build_tools import load_sphinx_config + ... + + # Since loadConfig overwrites settings from the global namespace, it has to be + # the last statement in the conf.py file + + load_sphinx_config(globals()) + + """ + + config_file = os.environ.get("SPHINX_CONF", None) + if (config_file is not None + and os.path.normpath(namespace["__file__"]) != os.path.normpath(config_file) ): + config_file = os.path.abspath(config_file) + + if os.path.isfile(config_file): + sys.stdout.write( + "load additional sphinx-config: %s\n" + % config_file) + config = namespace.copy() + config['__file__'] = config_file + execfile_(config_file, config) + del config['__file__'] + namespace.update(config) + else: + sys.stderr.write( + "WARNING: additional sphinx-config not found: %s\n" + % config_file)