Debian Codegraph @

doc/Makefile

raw
1 # Minimal makefile for Sphinx documentation
2 #
3
4 # You can set these variables from the command line, and also
5 # from the environment for the first two.
6 SPHINXOPTS ?= -c . -d .sphinx/.doctrees
7 SPHINXBUILD ?= sphinx-build
8 SPHINXDIR = .sphinx
9 SOURCEDIR = .
10 BUILDDIR = _build
11 VENVDIR = $(SPHINXDIR)/venv
12 VENV = $(VENVDIR)/bin/activate
13 SHELL = /usr/bin/bash
14
15 .PHONY: help woke-install install run html epub serve clean clean-doc \
16 spelling linkcheck woke Makefile
17
18 # Put it first so that "make" without argument is like "make help".
19 help: $(VENVDIR)
20 @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21
22 # Explicit target avoids fall-through to the "Makefile" target.
23 $(SPHINXDIR)/requirements.txt:
24 test -f $(SPHINXDIR)/requirements.txt
25
26 # If requirements are updated, venv should be rebuilt and timestamped.
27 $(VENVDIR): $(SPHINXDIR)/requirements.txt
28 @echo "... setting up virtualenv"
29 python3 -m venv $(VENVDIR)
30 . $(VENV); pip install --require-virtualenv \
31 --upgrade -r $(SPHINXDIR)/requirements.txt \
32 --log $(VENVDIR)/pip_install.log
33 @test ! -f $(VENVDIR)/pip_list.txt || \
34 mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak
35 @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt
36 @echo "\n" \
37 "--------------------------------------------------------------- \n" \
38 "* watch, build and serve the documentation: make run \n" \
39 "* only build: make html \n" \
40 "* only serve: make serve \n" \
41 "* clean built doc files: make clean-doc \n" \
42 "* clean full environment: make clean \n" \
43 "* check links: make linkcheck \n" \
44 "* check spelling: make spelling \n" \
45 "* check inclusive language: make woke \n" \
46 "* other possible targets: make <press TAB twice> \n" \
47 "--------------------------------------------------------------- \n"
48 @touch $(VENVDIR)
49
50 woke-install:
51 @type woke >/dev/null 2>&1 || \
52 { echo "Installing \"woke\" snap... \n"; sudo snap install woke; }
53
54 install: $(VENVDIR) woke-install
55
56 run: install
57 . $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --re-ignore '\.sphinx/breathe/doxygen/.*'
58
59 # Doesn't depend on $(BUILDDIR) to rebuild properly at every run.
60 html: install
61 . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS)
62
63 epub: install
64 . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt $(SPHINXOPTS)
65
66 serve: html
67 cd "$(BUILDDIR)"; python3 -m http.server 8000
68
69 clean: clean-doc
70 @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)"
71 rm -rf $(VENVDIR)
72 rm -rf .sphinx/.doctrees
73
74 clean-doc:
75 git clean -fx "$(BUILDDIR)"
76
77 spelling: html
78 . $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml
79
80 linkcheck: install
81 . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
82
83 woke: woke-install
84 woke *.{md,c,py} **/*.{md,c,py} --exit-1-on-failure \
85 -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml
86
87 # Catch-all target: route all unknown targets to Sphinx using the new
88 # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
89 %: Makefile
90 . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)