git.iko.soy/searx
on f9faafa help sign in
searx/utils/makefile.sphinx
220 lines 8.0 kB history raw
1# -*- coding: utf-8; mode: makefile-gmake -*-
3export DOCS_FOLDER DOCS_BUILD DOCS_DIST BOOKS_FOLDER BOOKS_DIST
5# You can set these variables from the command line.
6SPHINXOPTS ?=
7SPHINXBUILD ?= $(PY_ENV_BIN)/sphinx-build
8SPHINX_CONF ?= conf.py
10DOCS_FOLDER = ./docs
11DOCS_BUILD = ./$(LXC_ENV_FOLDER)build/docs
12DOCS_DIST = ./$(LXC_ENV_FOLDER)dist/docs
13GH_PAGES ?= gh-pages
15BOOKS_FOLDER = ./docs
16BOOKS_DIST = ./$(LXC_ENV_FOLDER)dist/books
18ifeq ($(KBUILD_VERBOSE),1)
19 SPHINX_VERBOSE = "-v"
20else
21 SPHINX_VERBOSE =
22endif
24## SPHINXVERS variable
25## ===================
26##
27## .. _requirement-specifiers: https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers
28##
29## Sphinx version to use, when building documentation. Set this when calling
30## build target. The default value is empty (install latest), to select a
31## specific version use a requirement-specifiers_. E.g. to build your target
32## 'doc' with a select sphinx-doc_ version 1.7.9::
33##
34## make SPHINXVERS='==1.7.9' docs
35##
36## To build with latest 1.7::
37##
38## make SPHINXVERS='>=1.7,<1.8' docs
39##
40SPHINXVERS ?=
42docs-help:
43 @echo 'makefile.sphinx:'
44 @echo ' docs-clean - clean intermediate doc objects'
45 @echo ' $(GH_PAGES) - create & upload github pages'
46 @echo ' sphinx-pdf - run sphinx latex & pdf targets'
47 echo ''
48 @echo ' books/{name}.html : build only the HTML of document {name}'
49 @echo ' valid values for books/{name}.html are:'
50 @echo ' $(BOOKS_HTML)' | $(FMT)
51 @echo ' books/{name}.pdf : build only the PDF of document {name}'
52 @echo ' valid values for books/{name}.pdf are:'
53 @echo ' $(BOOKS_PDF) ' | $(FMT)
55# ------------------------------------------------------------------------------
56# requirements
57# ------------------------------------------------------------------------------
59sphinx-doc-prebuilds:: $(PY_ENV)
61sphinx-doc: sphinx-doc-prebuilds
62 @echo "PYENV installing Sphinx$(SPHINXVERS)"
63 $(Q)$(PY_ENV_BIN)/pip install $(PIP_VERBOSE) 'Sphinx$(SPHINXVERS)'
65sphinx-live: sphinx-doc-prebuilds
66 @echo "PYENV installing Sphinx$(SPHINXVERS)"
67 $(Q)$(PY_ENV_BIN)/pip install $(PIP_VERBOSE) 'Sphinx$(SPHINXVERS)' sphinx-autobuild
70PHONY += msg-texlive texlive
72ifeq ($(shell which xelatex >/dev/null 2>&1; echo $$?), 1)
73texlive: msg-TeXLive
74 $(error The 'xelatex' command was not found)
75else
76texlive:
77 @:
78endif
80msg-texlive:
81 $(Q)echo "\n\
82The TeX/PDF output and the *math* extension require TexLive and latexmk:\n\n\
83 Make sure you have a updated TeXLive with XeTeX engine installed, grab it\n\
84 it from https://www.tug.org/texlive or install it from your package manager.\n\n\
85 Install latexmk from your package manager or visit https://ctan.org/pkg/latexmk\n\n\
86 Sphinx-doc produce (Xe)LaTeX files which might use additional TeX-packages\n\
87 and fonts. To process these LaTeX files, a TexLive installation with the\n\
88 additional packages is required. On debian based OS these requirements\n\
89 are installed by::\n\n\
90 sudo -H apt-get install\n\
91 latexmk\n\
92 texlive-base texlive-xetex texlive-latex-recommended\n\
93 texlive-extra-utils dvipng ttf-dejavu\n"
95# ------------------------------------------------------------------------------
96# commands
97# ------------------------------------------------------------------------------
99# $2 sphinx builder e.g. "html"
100# $3 path where configuration file (conf.py) is located
101# $4 sourcedir
102# $5 dest subfolder e.g. "man" for man pages at $(DOCS_DIST)/man
104quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5)
105 cmd_sphinx = SPHINX_CONF=$(abspath $4/$(SPHINX_CONF))\
106 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
107 -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5
109quiet_cmd_sphinx_autobuild = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5)
110 cmd_sphinx_autobuild = PATH="$(PY_ENV_BIN):$(PATH)" $(PY_ENV_BIN)/sphinx-autobuild $(SPHINX_VERBOSE) --poll -B --host 0.0.0.0 --port 8080 $(SPHINXOPTS)\
111 -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5
113quiet_cmd_sphinx_clean = CLEAN $@
114 cmd_sphinx_clean = rm -rf $(DOCS_BUILD) $(DOCS_DIST) $(GH_PAGES)/* $(GH_PAGES)/.buildinfo
116# ------------------------------------------------------------------------------
117# targets
118# ------------------------------------------------------------------------------
120# build PDF of whole documentation in: $(DOCS_DIST)/pdf
122PHONY += sphinx-pdf
123sphinx-pdf: sphinx-latex
124 $(Q)cd $(DOCS_BUILD)/latex/; make all-pdf
125 $(Q)mkdir -p $(DOCS_DIST)/pdf
126 $(Q)cp $(DOCS_BUILD)/latex/*.pdf $(DOCS_DIST)/pdf
127 @echo "SPHINX *.pdf --> file://$(abspath $(DOCS_DIST)/pdf)"
129PHONY += sphinx-latex
130sphinx-latex: texlive sphinx-doc
131 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
132 -b latex \
133 -c $(DOCS_FOLDER) \
134 -d $(DOCS_BUILD)/.doctrees \
135 $(DOCS_FOLDER) \
136 $(DOCS_BUILD)/latex
138# Sphinx projects, we call them *books* (what is more common). Books are
139# folders under $(BOOKS_FOLDER) containing a conf.py file. The HTML output goes
140# to folder $(BOOKS_DIST)/<name> while PDF is placed (BOOKS_DIST)/<name>/pdf
142BOOKS=$(patsubst $(BOOKS_FOLDER)/%/conf.py,books/%,$(wildcard $(BOOKS_FOLDER)/*/conf.py))
144# fine grained targets
145BOOKS_HTML = $(patsubst %,%.html,$(BOOKS))
146BOOKS_CLEAN = $(patsubst %,%.clean,$(BOOKS))
147BOOKS_LATEX = $(patsubst %,%.latex,$(BOOKS))
148BOOKS_PDF = $(patsubst %,%.pdf,$(BOOKS))
149BOOKS_LIVE = $(patsubst %,%.live,$(BOOKS))
151$(BOOKS_DIST):
152 mkdir -p $(BOOKS_DIST)
154PHONY += $(BOOKS_HTML)
155$(BOOKS_HTML): sphinx-doc | $(BOOKS_DIST)
156 SPHINX_CONF=$(patsubst books/%.html,%,$@)/conf.py \
157 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
158 -b html \
159 -c $(DOCS_FOLDER) \
160 -d $(DOCS_BUILD)/books/$(patsubst books/%.html,%,$@)/.doctrees \
161 $(BOOKS_FOLDER)/$(patsubst books/%.html,%,$@) \
162 $(BOOKS_DIST)/$(patsubst books/%.html,%,$@)
163 @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))"
165PHONY += $(BOOKS_HTML)
166$(BOOKS_LIVE): sphinx-live | $(BOOKS_DIST)
167 PATH="$(PY_ENV_BIN):$(PATH)" \
168 SPHINX_CONF=$(patsubst books/%.live,%,$@)/conf.py \
169 $(PY_ENV_BIN)/sphinx-autobuild --poll -B --host 0.0.0.0 --port 8080 $(SPHINX_VERBOSE) $(SPHINXOPTS)\
170 -b html \
171 -c $(DOCS_FOLDER) \
172 -d $(DOCS_BUILD)/books/$(patsubst books/%.live,%,$@)/.doctrees \
173 $(BOOKS_FOLDER)/$(patsubst books/%.live,%,$@) \
174 $(BOOKS_DIST)/$(patsubst books/%.live,%,$@)
176$(BOOKS_PDF): %.pdf : %.latex
177 $(Q)cd $(DOCS_BUILD)/latex/$(patsubst books/%.pdf,%,$@); make all-pdf
178 $(Q)mkdir -p $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@)/pdf
179 $(Q)cp -v $(DOCS_BUILD)/latex/$(patsubst books/%.pdf,%,$@)/*.pdf $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@)/pdf
180 @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@))/pdf"
182PHONY += $(BOOKS_LATEX)
183$(BOOKS_LATEX): sphinx-doc | $(BOOKS_DIST)
184 SPHINX_CONF=$(patsubst books/%.latex,%,$@)/conf.py \
185 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
186 -b latex \
187 -c $(DOCS_FOLDER) \
188 -d $(DOCS_BUILD)/books/$(patsubst books/%.latex,%,$@)/.doctrees \
189 $(BOOKS_FOLDER)/$(patsubst books/%.latex,%,$@) \
190 $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@)
191 @echo "SPHINX $@ --> file://$(abspath $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@))"
193$(BOOKS_CLEAN):
194 $(Q)rm -rf $(BOOKS_DIST)/$(patsubst books/%.clean,%,$@) \
195 $(DOCS_BUILD)/books/$(patsubst books/%.clean,%,$@) \
196 $(DOCS_BUILD)/latex/$(patsubst books/%.clean,%,$@)
198# github pages
200PHONY += $(GH_PAGES)
201$(GH_PAGES)::
202 $(MAKE) docs
203 [ -d "gh-pages/.git" ] || git clone $(GIT_URL) gh-pages
204 -cd $(GH_PAGES); git checkout gh-pages >/dev/null
205 -cd $(GH_PAGES); git pull
206 -cd $(GH_PAGES); ls -A | grep -v '.git$$' | xargs rm -rf
207 cp -r $(DOCS_DIST)/* $(GH_PAGES)/
208 touch $(GH_PAGES)/.nojekyll
209 echo "<html><head><META http-equiv='refresh' content='0;URL=index.html'></head></html>" > $(GH_PAGES)/404.html
210 cd $(GH_PAGES);\
211 git add --all . ;\
212 git commit -m "gh-pages: updated" ;\
213 git push origin gh-pages
216PHONY += docs-clean
217docs-clean: $(BOOKS_CLEAN)
218 $(call cmd,sphinx_clean)
220.PHONY: $(PHONY)