git.iko.soy/searx
on update_data_update_languages.py help sign in
searx/utils/makefile.sphinx
199 lines 7.4 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 ?= build/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
25docs-help:
26 @echo 'makefile.sphinx:'
27 @echo ' docs-clean - clean intermediate doc objects'
28 @echo ' $(GH_PAGES) - create & upload github pages'
29 @echo ' sphinx-pdf - run sphinx latex & pdf targets'
30 @echo ''
31 @echo ' books/{name}.html : build only the HTML of document {name}'
32 @echo ' valid values for books/{name}.html are:'
33 @echo ' $(BOOKS_HTML)' | $(FMT)
34 @echo ' books/{name}.pdf : build only the PDF of document {name}'
35 @echo ' valid values for books/{name}.pdf are:'
36 @echo ' $(BOOKS_PDF) ' | $(FMT)
38# ------------------------------------------------------------------------------
39# requirements
40# ------------------------------------------------------------------------------
42PHONY += msg-texlive texlive
44ifeq ($(shell which xelatex >/dev/null 2>&1; echo $$?), 1)
45texlive: msg-TeXLive
46 $(error The 'xelatex' command was not found)
47else
48texlive:
49 @:
50endif
52msg-texlive:
53 $(Q)echo "\n\
54The TeX/PDF output and the *math* extension require TexLive and latexmk:\n\n\
55 Make sure you have a updated TeXLive with XeTeX engine installed, grab it\n\
56 it from https://www.tug.org/texlive or install it from your package manager.\n\n\
57 Install latexmk from your package manager or visit https://ctan.org/pkg/latexmk\n\n\
58 Sphinx-doc produce (Xe)LaTeX files which might use additional TeX-packages\n\
59 and fonts. To process these LaTeX files, a TexLive installation with the\n\
60 additional packages is required. On debian based OS these requirements\n\
61 are installed by::\n\n\
62 sudo -H apt-get install\n\
63 latexmk\n\
64 texlive-base texlive-xetex texlive-latex-recommended\n\
65 texlive-extra-utils dvipng ttf-dejavu\n"
67# ------------------------------------------------------------------------------
68# commands
69# ------------------------------------------------------------------------------
71# $2 sphinx builder e.g. "html"
72# $3 path where configuration file (conf.py) is located
73# $4 sourcedir
74# $5 dest subfolder e.g. "man" for man pages at $(DOCS_DIST)/man
76quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5)
77 cmd_sphinx = SPHINX_CONF=$(abspath $4/$(SPHINX_CONF))\
78 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
79 -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5
81quiet_cmd_sphinx_autobuild = SPHINX $@ --> file://$(abspath $(DOCS_DIST)/$5)
82 cmd_sphinx_autobuild = PATH="$(PY_ENV_BIN):$(PATH)" $(PY_ENV_BIN)/sphinx-autobuild $(SPHINX_VERBOSE) --open-browser --host 0.0.0.0 $(SPHINXOPTS)\
83 -b $2 -c $3 -d $(DOCS_BUILD)/.doctrees $4 $(DOCS_DIST)/$5
85quiet_cmd_sphinx_clean = CLEAN $@
86 cmd_sphinx_clean = rm -rf $(DOCS_BUILD) $(DOCS_DIST) $(GH_PAGES)/* $(GH_PAGES)/.buildinfo
88# ------------------------------------------------------------------------------
89# targets
90# ------------------------------------------------------------------------------
92# build PDF of whole documentation in: $(DOCS_DIST)/pdf
94PHONY += sphinx-pdf
95sphinx-pdf: sphinx-latex
96 $(Q)cd $(DOCS_BUILD)/latex/; make all-pdf
97 $(Q)mkdir -p $(DOCS_DIST)/pdf
98 $(Q)cp $(DOCS_BUILD)/latex/*.pdf $(DOCS_DIST)/pdf
99 @echo "SPHINX *.pdf --> file://$(abspath $(DOCS_DIST)/pdf)"
101PHONY += sphinx-latex
102sphinx-latex: pyenvinstall texlive
103 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
104 -b latex \
105 -c $(DOCS_FOLDER) \
106 -d $(DOCS_BUILD)/.doctrees \
107 $(DOCS_FOLDER) \
108 $(DOCS_BUILD)/latex
110# Sphinx projects, we call them *books* (what is more common). Books are
111# folders under $(BOOKS_FOLDER) containing a conf.py file. The HTML output goes
112# to folder $(BOOKS_DIST)/<name> while PDF is placed (BOOKS_DIST)/<name>/pdf
114BOOKS=$(patsubst $(BOOKS_FOLDER)/%/conf.py,books/%,$(wildcard $(BOOKS_FOLDER)/*/conf.py))
116# fine grained targets
117BOOKS_HTML = $(patsubst %,%.html,$(BOOKS))
118BOOKS_CLEAN = $(patsubst %,%.clean,$(BOOKS))
119BOOKS_LATEX = $(patsubst %,%.latex,$(BOOKS))
120BOOKS_PDF = $(patsubst %,%.pdf,$(BOOKS))
121BOOKS_LIVE = $(patsubst %,%.live,$(BOOKS))
123$(BOOKS_DIST):
124 mkdir -p $(BOOKS_DIST)
126PHONY += $(BOOKS_HTML)
127$(BOOKS_HTML): pyenvinstall | $(BOOKS_DIST)
128 SPHINX_CONF=$(patsubst books/%.html,%,$@)/conf.py \
129 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
130 -b html \
131 -c $(DOCS_FOLDER) \
132 -d $(DOCS_BUILD)/books/$(patsubst books/%.html,%,$@)/.doctrees \
133 $(BOOKS_FOLDER)/$(patsubst books/%.html,%,$@) \
134 $(BOOKS_DIST)/$(patsubst books/%.html,%,$@)
135 @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.html,%,$@))"
137PHONY += $(BOOKS_HTML)
138$(BOOKS_LIVE): pyenvinstall | $(BOOKS_DIST)
139 PATH="$(PY_ENV_BIN):$(PATH)" \
140 SPHINX_CONF=$(patsubst books/%.live,%,$@)/conf.py \
141 $(PY_ENV_BIN)/sphinx-autobuild --poll -B --host 0.0.0.0 --port 8080 $(SPHINX_VERBOSE) $(SPHINXOPTS)\
142 -b html \
143 -c $(DOCS_FOLDER) \
144 -d $(DOCS_BUILD)/books/$(patsubst books/%.live,%,$@)/.doctrees \
145 $(BOOKS_FOLDER)/$(patsubst books/%.live,%,$@) \
146 $(BOOKS_DIST)/$(patsubst books/%.live,%,$@)
148$(BOOKS_PDF): %.pdf : %.latex
149 $(Q)cd $(DOCS_BUILD)/latex/$(patsubst books/%.pdf,%,$@); make all-pdf
150 $(Q)mkdir -p $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@)/pdf
151 $(Q)cp -v $(DOCS_BUILD)/latex/$(patsubst books/%.pdf,%,$@)/*.pdf $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@)/pdf
152 @echo "SPHINX $@ --> file://$(abspath $(BOOKS_DIST)/$(patsubst books/%.pdf,%,$@))/pdf"
154PHONY += $(BOOKS_LATEX)
155$(BOOKS_LATEX): pyenvinstall | $(BOOKS_DIST)
156 SPHINX_CONF=$(patsubst books/%.latex,%,$@)/conf.py \
157 $(SPHINXBUILD) $(SPHINX_VERBOSE) $(SPHINXOPTS)\
158 -b latex \
159 -c $(DOCS_FOLDER) \
160 -d $(DOCS_BUILD)/books/$(patsubst books/%.latex,%,$@)/.doctrees \
161 $(BOOKS_FOLDER)/$(patsubst books/%.latex,%,$@) \
162 $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@)
163 @echo "SPHINX $@ --> file://$(abspath $(DOCS_BUILD)/latex/$(patsubst books/%.latex,%,$@))"
165$(BOOKS_CLEAN):
166 $(Q)rm -rf $(BOOKS_DIST)/$(patsubst books/%.clean,%,$@) \
167 $(DOCS_BUILD)/books/$(patsubst books/%.clean,%,$@) \
168 $(DOCS_BUILD)/latex/$(patsubst books/%.clean,%,$@)
170# github pages
171PHONY += prepare-gh-pages
172prepare-gh-pages:
173 cp -r $(DOCS_DIST)/* $(GH_PAGES)/
174 touch $(GH_PAGES)/.nojekyll
175 echo "<html><head><META http-equiv='refresh' content='0;URL=index.html'></head></html>" > $(GH_PAGES)/404.html
177PHONY += gh-pages
178gh-pages: docs-clean docs
179 - git worktree remove -f $(GH_PAGES) || exit 0
180 - git branch -D gh-pages || exit 0
181 git worktree add --no-checkout $(GH_PAGES) master
182 cd $(GH_PAGES); git checkout --orphan gh-pages && git rm -rfq .
183 $(MAKE) prepare-gh-pages
184 cd $(GH_PAGES);\
185 git add --all . ;\
186 git commit -q -m "make gh-pages: from $(shell git config --get remote.origin.url)@$(shell git rev-parse HEAD)" ;\
187 git push -f origin gh-pages
189PHONY += ci-gh-pages
190ci-gh-pages: docs-clean docs
191 rm -Rf $(GH_PAGES)
192 mkdir -p $(GH_PAGES)
193 $(MAKE) prepare-gh-pages
195PHONY += docs-clean
196docs-clean: $(BOOKS_CLEAN)
197 $(call cmd,sphinx_clean)
199.PHONY: $(PHONY)