1# -*- coding: utf-8; mode: makefile-gmake -*- 2 3export DOCS_FOLDER DOCS_BUILD DOCS_DIST BOOKS_FOLDER BOOKS_DIST 4 5# You can set these variables from the command line. 6SPHINXOPTS ?= 7SPHINXBUILD ?= $(PY_ENV_BIN)/sphinx-build 8SPHINX_CONF ?= conf.py 9 10DOCS_FOLDER = ./docs 11DOCS_BUILD = ./$(LXC_ENV_FOLDER)build/docs 12DOCS_DIST = ./$(LXC_ENV_FOLDER)dist/docs 13GH_PAGES ?= build/gh-pages 14 15BOOKS_FOLDER = ./docs 16BOOKS_DIST = ./$(LXC_ENV_FOLDER)dist/books 17 18ifeq ($(KBUILD_VERBOSE),1) 19 SPHINX_VERBOSE = "-v" 20else 21 SPHINX_VERBOSE = 22endif 23 24 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) 37 38# ------------------------------------------------------------------------------ 39# requirements 40# ------------------------------------------------------------------------------ 41 42PHONY += msg-texlive texlive 43 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 51 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" 66 67# ------------------------------------------------------------------------------ 68# commands 69# ------------------------------------------------------------------------------ 70 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 75 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 80 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 84 85quiet_cmd_sphinx_clean = CLEAN $@ 86 cmd_sphinx_clean = rm -rf $(DOCS_BUILD) $(DOCS_DIST) $(GH_PAGES)/* $(GH_PAGES)/.buildinfo 87 88# ------------------------------------------------------------------------------ 89# targets 90# ------------------------------------------------------------------------------ 91 92# build PDF of whole documentation in: $(DOCS_DIST)/pdf 93 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)" 100 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 109 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 113 114BOOKS=$(patsubst $(BOOKS_FOLDER)/%/conf.py,books/%,$(wildcard $(BOOKS_FOLDER)/*/conf.py)) 115 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)) 122 123$(BOOKS_DIST): 124 mkdir -p $(BOOKS_DIST) 125 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,%,$@))" 136 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,%,$@) 147 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" 153 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,%,$@))" 164 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,%,$@) 169 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 176 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 188 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 194 195PHONY += docs-clean 196docs-clean: $(BOOKS_CLEAN) 197 $(call cmd,sphinx_clean) 198 199.PHONY: $(PHONY) 200