Debian Codegraph @

doc/sphinx/Makefile

raw
1 # Minimal makefile for Sphinx documentation
2 #
3 # Add your customisation to `Makefile` instead.
4
5 # You can set these variables from the command line, and also
6 # from the environment for the first two.
7
8 SPHINX_DIR ?= .sphinx
9 SPHINX_DOCTREES ?= $(SPHINX_DIR)/.doctrees
10 SPHINX_OPTS ?= -c . -d $(SPHINX_DOCTREES) -j auto $(EXTRA_SPHINXOPTS)
11 SPHINX_BUILD ?= $(DOCS_VENVDIR)/bin/sphinx-build
12 SPHINX_HOST ?= 127.0.0.1
13 SPHINX_PORT ?= 8000
14 DOCS_VENVDIR ?= .venv
15 DOCS_VENV ?= $(DOCS_VENVDIR)/bin/activate
16 DOCS_SOURCEDIR ?= .
17 DOCS_BUILDDIR ?= _build
18 DOCS_PDFPACKAGES ?= latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng
19 DOCS_VOCAB ?= $(SPHINX_DIR)/styles/config/vocabularies/Canonical
20 VALE_DIR ?= $(DOCS_VENVDIR)/lib/python*/site-packages/vale
21 VALE_CONFIG ?= $(SPHINX_DIR)/vale.ini
22 PA11Y_CMD ?= $(SPHINX_DIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINX_DIR)/pa11y.json
23 CONFIRM_SUDO ?= N
24 CHECK_PATH ?= $(filter-out $(DOCS_VENVDIR),$(wildcard *))
25 PROJECT_ROOT ?= $(shell readlink -f ../../)
26
27 export MIR_BUILD_API_DOCS
28 # Put it first so that "make" without argument is like "make help".
29 help:
30 @echo
31 @echo "-------------------------------------------------------------"
32 @echo "* watch, build and serve the documentation: make run"
33 @echo "* only build: make html"
34 @echo "* only serve: make serve"
35 @echo "* clean built doc files: make clean-doc"
36 @echo "* clean full environment: make clean"
37 @echo "* check links: make linkcheck"
38 @echo "* check markdown: make lint-md"
39 @echo "* check spelling: make spelling"
40 @echo "* check spelling (without building again): make spellcheck"
41 @echo "* check inclusive language: make woke"
42 @echo "* check accessibility: make pa11y"
43 @echo "* check style guide compliance: make vale"
44 @echo "* check style guide compliance on target: make vale CHECK_PATH=*"
45 @echo "* other possible targets: make <TAB twice>"
46 @echo "-------------------------------------------------------------"
47 @echo
48
49 .PHONY: help full-help html epub pdf linkcheck spelling spellcheck woke \
50 vale pa11y run serve install pa11y-install \
51 vale-install pdf-prep pdf-prep-force clean clean-doc \
52 update lint-md
53
54 full-help: $(DOCS_VENVDIR)
55 @. $(DOCS_VENV); $(SPHINX_BUILD) -M help "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(O)
56 @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m"
57 @echo "Run 'make help' to see supported targets."
58
59 # If requirements are updated, venv should be rebuilt and timestamped.
60 $(DOCS_VENVDIR):
61 @echo "... setting up virtualenv"
62 python3 -m venv $(DOCS_VENVDIR) || { echo "You must install python3-venv before you can build the documentation."; exit 1; }
63 . $(DOCS_VENV); pip install $(PIPOPTS) --require-virtualenv \
64 --upgrade -r requirements.txt \
65 --log $(DOCS_VENVDIR)/pip_install.log
66 @test ! -f $(DOCS_VENVDIR)/pip_list.txt || \
67 mv $(DOCS_VENVDIR)/pip_list.txt $(DOCS_VENVDIR)/pip_list.txt.bak
68 @. $(DOCS_VENV); pip list --local --format=freeze > $(DOCS_VENVDIR)/pip_list.txt
69 @touch $(DOCS_VENVDIR)
70
71 pa11y-install:
72 @command -v $(PA11Y_CMD) >/dev/null || { \
73 echo "Installing \"pa11y\" from npm..."; echo; \
74 mkdir -p $(SPHINX_DIR)/node_modules/ ; \
75 npm install --prefix $(SPHINX_DIR) pa11y; \
76 }
77
78 pymarkdownlnt-install: install
79 @. $(DOCS_VENV); test -d $(DOCS_VENVDIR)/lib/python*/site-packages/pymarkdown || pip install pymarkdownlnt==0.9.35
80
81 install: $(DOCS_VENVDIR)
82
83 run: install
84 . $(DOCS_VENV); $(DOCS_VENVDIR)/bin/sphinx-autobuild -b dirhtml --host $(SPHINX_HOST) --port $(SPHINX_PORT) "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS)
85
86 # Does not depend on $(DOCS_BUILDDIR) to rebuild properly at every run.
87 html: install
88 . $(DOCS_VENV); $(SPHINX_BUILD) --fail-on-warning --keep-going -b dirhtml "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS)
89
90 epub: install
91 . $(DOCS_VENV); $(SPHINX_BUILD) -b epub "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" -w $(SPHINX_DIR)/warnings.txt $(SPHINX_OPTS)
92
93 serve: html
94 cd "$(DOCS_BUILDDIR)"; python3 -m http.server --bind $(SPHINX_HOST) $(SPHINX_PORT)
95
96 clean: clean-doc
97 # https://github.com/canonical/sphinx-docs-starter-pack/issues/435
98 @test ! -e "$(DOCS_VENVDIR)" -o -d "$(DOCS_VENVDIR)"
99 rm -rf $(DOCS_VENVDIR)
100 rm -rf $(SPHINX_DIR)/node_modules/
101 rm -rf $(SPHINX_DIR)/styles
102 rm -rf $(VALE_CONFIG)
103
104 clean-doc:
105 git clean -fx "$(DOCS_BUILDDIR)"
106 rm -rf $(SPHINX_DOCTREES)
107
108 linkcheck: install
109 . $(DOCS_VENV) ; $(SPHINX_BUILD) -b linkcheck -q "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) || { grep --color -F "[broken]" "$(DOCS_BUILDDIR)/output.txt"; exit 1; }
110 exit 0
111
112 linkcheck-with-dependencies: install
113 sudo add-apt-repository --yes ppa:mir-team/dev
114 sudo apt-get --yes build-dep $(PROJECT_ROOT)
115 . $(DOCS_VENV); cmake -DMIR_ENABLE_TESTS=NO -DMIR_PLATFORM=x11 "$(PROJECT_ROOT)" -B "$(PROJECT_ROOT)"
116 @$(MAKE) linkcheck
117
118 pa11y: pa11y-install html
119 find $(DOCS_BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y_CMD)
120
121 # Without --return-code-scheme explicit, pymarkdownlnt returns 1 for multiple scenarios
122 # By using the explicit scheme, it only returns 1 when no files are found,
123 # which should not result in failure
124 lint-md: pymarkdownlnt-install
125 @. $(DOCS_VENV); pymarkdownlnt \
126 --config $(SPHINX_DIR)/.pymarkdown.json \
127 --return-code-scheme explicit \
128 scan \
129 --recurse \
130 --exclude=$(SPHINX_DIR)/** \
131 --exclude=$(DOCS_VENVDIR)/** \
132 $(DOCS_SOURCEDIR); \
133 status=$$?; \
134 if [ $$status -eq 1 ]; then \
135 echo "No Markdown files selected for linting"; \
136 exit 0; \
137 fi; \
138 echo "pymarkdownlnt exited with code $$status"; \
139 exit $$status;
140
141 vale-install: install
142 @. $(DOCS_VENV); test -f $(VALE_CONFIG) || python3 $(SPHINX_DIR)/get_vale_conf.py
143 @echo '.Name=="Canonical.400-Enforce-inclusive-terms"' > $(SPHINX_DIR)/styles/woke.filter
144 @echo '.Level=="error" and .Name!="Canonical.500-Repeated-words" and .Name!="Canonical.000-US-spellcheck"' > $(SPHINX_DIR)/styles/error.filter
145 @echo '.Name=="Canonical.000-US-spellcheck"' > $(SPHINX_DIR)/styles/spelling.filter
146 @. $(DOCS_VENV); find $(VALE_DIR)/vale_bin -size 195c -exec vale --version \;
147
148 woke: vale-install
149 @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt
150 @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt
151 @echo "Running Vale acceptable term check against $(CHECK_PATH). To change target set CHECK_PATH= with make command"
152 @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/woke.filter' --glob='*.{md,rst}' $(CHECK_PATH)
153 @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt
154
155 vale: vale-install
156 @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt
157 @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt
158 @echo "Running Vale against $(CHECK_PATH). To change target set CHECK_PATH= with make command"
159 @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/error.filter' --glob='*.{md,rst}' $(CHECK_PATH)
160 @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt
161
162 spelling: vale-install
163 @cat $(DOCS_VOCAB)/accept.txt > $(DOCS_VOCAB)/accept_backup.txt
164 @cat $(DOCS_SOURCEDIR)/.custom_wordlist.txt >> $(DOCS_VOCAB)/accept.txt
165 @echo "Running Vale against $(CHECK_PATH). To change target set CHECK_PATH= with make command"
166 @. $(DOCS_VENV); vale --config="$(VALE_CONFIG)" --filter='$(SPHINX_DIR)/styles/spelling.filter' --glob='*.{md,rst}' $(CHECK_PATH)
167 @cat $(DOCS_VOCAB)/accept_backup.txt > $(DOCS_VOCAB)/accept.txt && rm $(DOCS_VOCAB)/accept_backup.txt
168
169 spellcheck: spelling
170 @echo "Please note that the \`make spellcheck\` command is being deprecated in favor of \`make spelling\`"
171
172 pdf-prep: install
173 @for packageName in $(DOCS_PDFPACKAGES); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \
174 grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \
175 (echo; echo "PDF generation requires the installation of the following packages: $(DOCS_PDFPACKAGES)" && \
176 echo "" && echo "Run 'sudo make pdf-prep-force' to install these packages" && echo "" && echo \
177 "Please be aware these packages will be installed to your system") && exit 1 ; done
178
179 pdf-prep-force:
180 apt-get update
181 apt-get upgrade -y
182 apt-get install --no-install-recommends -y $(DOCS_PDFPACKAGES) \
183
184 pdf: pdf-prep
185 @. $(DOCS_VENV); $(SPHINX_BUILD) -M latexpdf "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS)
186 @rm ./$(DOCS_BUILDDIR)/latex/front-page-light.pdf || true
187 @rm ./$(DOCS_BUILDDIR)/latex/normal-page-footer.pdf || true
188 @find ./$(DOCS_BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(DOCS_BUILDDIR) {} +
189 @rm -r $(DOCS_BUILDDIR)/latex
190 @echo
191 @echo "Output can be found in ./$(DOCS_BUILDDIR)"
192 @echo
193
194 update: install
195 @. $(DOCS_VENV); .sphinx/update_sp.py
196
197 # Catch-all target: route all unknown targets to Sphinx using the new
198 # "make mode" option. $(O) is meant as a shortcut for $(SPHINX_OPTS).
199 %:
200 $(MAKE) --no-print-directory install
201 . $(DOCS_VENV); $(SPHINX_BUILD) -M $@ "$(DOCS_SOURCEDIR)" "$(DOCS_BUILDDIR)" $(SPHINX_OPTS) $(O)