| 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) |