1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
|
# Makefile for Sphinx documentation
.DEFAULT_GOAL = help
SHELL = bash
# You can set these variables from the command line.
SPHINXOPTS ?=
PAPER ?=
# Internal variables.
SPHINXBUILD = "$(realpath .venv/bin/sphinx-build)"
SPHINXAUTOBUILD = "$(realpath .venv/bin/sphinx-autobuild)"
DOCS_DIR = ./docs/
BUILDDIR = ../_build
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
#TODO: VALEFILES := $(shell find $(DOCS_DIR) -type f -name "*.md" -print)
#TODO: VALEOPTS ?=
PYTHONVERSION = >=3.10,<3.15
VERSION := $(shell uv version --short)
# Add the following 'help' target to your Makefile
# And add help text after each target name starting with '\#\#'
.PHONY: help
help: # This help message
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
# environment management
.PHONY: dev
dev: ## Install required Python, create Python virtual environment, install tox-uv plugin, and install package requirements
@uv python install "$(PYTHONVERSION)"
@uv venv --python "$(PYTHONVERSION)"
@uv tool install tox --with tox-uv
@uv sync
.PHONY: sync
sync: ## Sync package requirements
@uv sync
.PHONY: init
init: clean clean-python dev ## Clean docs build directory and initialize Python virtual environment
.PHONY: clean
clean: ## Clean docs build directory
cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
.PHONY: clean-python
clean-python: clean
rm -rf .venv/
# /environment management
# documentation builders
.PHONY: html
html: dev ## Build standalone HTML files
cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: livehtml
livehtml: dev ## Rebuild Sphinx documentation on changes, with live-reload in the browser
cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \
--watch "../src/sphinxcontrib/" \
--ignore "*.swp" \
--port 8050 \
-b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
.PHONY: dirhtml
dirhtml: dev ## Build HTML files named index.html in directories
cd $(DOCS_DIR) && $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
singlehtml: dev ## Build a single large HTML file
cd $(DOCS_DIR) && $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: pickle
pickle: dev ## Build pickle files
cd $(DOCS_DIR) && $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
.PHONY: json
json: dev ## Build JSON files
cd $(DOCS_DIR) && $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
.PHONY: htmlhelp
htmlhelp: dev ## Build HTML files and an HTML help project
cd $(DOCS_DIR) && $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
.PHONY: qthelp
qthelp: dev ## Build HTML files and a qthelp project
cd $(DOCS_DIR) && $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sphinxcontrib-httpdomain.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sphinxcontrib-httpdomain.qhc"
.PHONY: devhelp
devhelp: dev ## Build HTML files and a Devhelp project
cd $(DOCS_DIR) && $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/sphinxcontrib-httpdomain"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sphinxcontrib-httpdomain"
@echo "# devhelp"
.PHONY: epub
epub: dev ## Build an epub
cd $(DOCS_DIR) && $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
.PHONY: latex
latex: dev ## Build LaTeX files, you can set PAPER=a4 or PAPER=letter
cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
.PHONY: latexpdf
latexpdf: dev ## Build LaTeX files and run them through pdflatex
cd $(DOCS_DIR) && $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: text
text: dev ## Build text files
cd $(DOCS_DIR) && cd $(DOCS_DIR) && $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
.PHONY: man
man: dev ## Build manual pages
cd $(DOCS_DIR) && $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: texinfo
texinfo: dev ## Build Texinfo files
cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
.PHONY: info
info: dev ## Build Texinfo files and run them through makeinfo
cd $(DOCS_DIR) && $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
.PHONY: gettext
gettext: dev ## Build PO message catalogs
cd $(DOCS_DIR) && $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
.PHONY: changes
changes: dev ## Build an overview of all changed, added, or deprecated items
cd $(DOCS_DIR) && cd $(DOCS_DIR) && $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
# /documentation builders
# test
.PHONY: linkcheck
linkcheck: dev ## Check links
cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/."
.PHONY: linkcheckbroken
linkcheckbroken: dev ## Run linkcheck and show only broken links
cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' grep -wi "broken\|redirect" --color=always | GREP_COLORS='0;31' grep -vi "https://github.com/plone/volto/issues/" --color=always && if test $$? = 0; then exit 1; fi || test $$? = 1
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/ ."
#TODO .PHONY: vale
#vale: dev ## Run Vale style, grammar, and spell checks
# @uv run vale sync
# @uv run vale --no-wrap $(VALEOPTS) $(VALEFILES)
# @echo
# @echo "Vale is finished; look for any errors in the above output."
.PHONY: doctest
doctest: dev ## Run all doctests embedded in the documentation (if enabled)
cd $(DOCS_DIR) && $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
.PHONY: test
test: clean linkcheckbroken doctest ## Clean docs build, then run linkcheckbroken and doctest
#test: clean vale linkcheckbroken doctest ## Clean docs build, then run vale and linkcheckbroken
# /test
# development
.PHONY: rtd-prepare
rtd-prepare: ## Prepare environment on Read the Docs
asdf plugin add uv
asdf install uv latest
asdf global uv latest
.PHONY: rtd-pr-preview
rtd-pr-preview: rtd-prepare dev ## Build pull request preview on Read the Docs
cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
.PHONY: dist
dist: ## Clean dist, then build the project
@git add .
@git commit -m "Release $(VERSION)"
@git tag $(VERSION)
@git push --atomic origin main $(VERSION)
@rm -rf dist
@uv build
.PHONY: all
all: clean linkcheck html ## Clean docs build, then run linkcheck, and build html
#all: clean vale linkcheck html ## Clean docs build, then run vale and linkcheck, and build html
# /development
|
