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