Skip to content

Commit cedcb49

Browse files
AA-TurnerAA-Turner
authored
Modernise the make templates (#1370)
1 parent 9447a88 commit cedcb49

File tree

3 files changed

+144
-271
lines changed

3 files changed

+144
-271
lines changed

‎Makefile‎

Lines changed: 17 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -10,50 +10,31 @@ SPHINXOPTS = --fail-on-warning --keep-going
1010
BUILDDIR = _build
1111
BUILDER = html
1212
JOBS = auto
13-
PAPER =
1413
SPHINXLINT = $(VENVDIR)/bin/sphinx-lint
1514
REQUIREMENTS = requirements.txt
1615

1716
# Internal variables.
18-
PAPEROPT_a4 = --define latex_paper_size=a4
19-
PAPEROPT_letter = --define latex_paper_size=letter
20-
ALLSPHINXOPTS = --builder $(BUILDER) \
21-
--doctree-dir $(BUILDDIR)/doctrees \
22-
--jobs $(JOBS) \
23-
$(PAPEROPT_$(PAPER)) \
24-
$(SPHINXOPTS) \
25-
. $(BUILDDIR)/$(BUILDER)
17+
_ALL_SPHINX_OPTS = --jobs $(JOBS) $(SPHINXOPTS)
18+
_RELEASE_CYCLE = include/branches.csv \
19+
include/end-of-life.csv \
20+
include/release-cycle.svg
2621

2722
.PHONY: help
2823
help:
2924
@echo "Please use \`make <target>' where <target> is one of"
3025
@echo " venv to create a venv with necessary tools"
3126
@echo " html to make standalone HTML files"
27+
@echo " linkcheck to check all external links for integrity"
3228
@echo " htmlview to open the index page built by the html target in your browser"
3329
@echo " htmllive to rebuild and reload HTML files in your browser"
3430
@echo " clean to remove the venv and build files"
35-
@echo " dirhtml to make HTML files named index.html in directories"
36-
@echo " singlehtml to make a single large HTML file"
37-
@echo " pickle to make pickle files"
38-
@echo " json to make JSON files"
39-
@echo " htmlhelp to make HTML files and a HTML help project"
40-
@echo " qthelp to make HTML files and a qthelp project"
41-
@echo " devhelp to make HTML files and a Devhelp project"
42-
@echo " epub to make an epub"
43-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
44-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
45-
@echo " text to make text files"
46-
@echo " man to make manual pages"
47-
@echo " changes to make an overview of all changed/added/deprecated items"
48-
@echo " linkcheck to check all external links for integrity"
49-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
5031
@echo " check to run a check for frequent markup errors"
5132
@echo " lint to lint all the files"
52-
@echo " versions to update release cycle after changing release-cycle.json"
5333

5434
.PHONY: clean
5535
clean: clean-venv
5636
-rm -rf $(BUILDDIR)/*
37+
-rm -rf $(_RELEASE_CYCLE)
5738

5839
.PHONY: clean-venv
5940
clean-venv:
@@ -83,89 +64,6 @@ ensure-venv:
8364
echo "The venv has been created in the $(VENVDIR) directory"; \
8465
fi
8566

86-
.PHONY: html
87-
html: ensure-venv versions
88-
$(SPHINXBUILD) $(ALLSPHINXOPTS)
89-
90-
.PHONY: dirhtml
91-
dirhtml: BUILDER = dirhtml
92-
dirhtml: html
93-
94-
.PHONY: singlehtml
95-
singlehtml: BUILDER = singlehtml
96-
singlehtml: html
97-
98-
.PHONY: pickle
99-
pickle: BUILDER = pickle
100-
pickle: html
101-
@echo
102-
@echo "Build finished; now you can process the pickle files."
103-
104-
.PHONY: json
105-
json: BUILDER = json
106-
json: html
107-
@echo
108-
@echo "Build finished; now you can process the JSON files."
109-
110-
.PHONY: htmlhelp
111-
htmlhelp: BUILDER = htmlhelp
112-
htmlhelp: html
113-
@echo
114-
@echo "Build finished; now you can run HTML Help Workshop with the" \
115-
".hhp project file in $(BUILDDIR)/$(BUILDER)."
116-
117-
.PHONY: qthelp
118-
qthelp: BUILDER = qthelp
119-
qthelp: html
120-
121-
.PHONY: devhelp
122-
devhelp: BUILDER = devhelp
123-
devhelp: html
124-
125-
.PHONY: epub
126-
epub: BUILDER = epub
127-
epub: html
128-
@echo
129-
@echo "Build finished. The epub file is in $(BUILDDIR)/$(BUILDER)."
130-
131-
.PHONY: latex
132-
latex: BUILDER = latex
133-
latex: html
134-
135-
.PHONY: latexpdf
136-
latexpdf: BUILDER = latex
137-
latexpdf: html
138-
@echo "Running LaTeX files through pdflatex..."
139-
make -C $(BUILDDIR)/latex all-pdf
140-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/$(BUILDER)."
141-
142-
.PHONY: text
143-
text: BUILDER = text
144-
text: html
145-
146-
.PHONY: man
147-
man: BUILDER = man
148-
man: html
149-
@echo
150-
@echo "Build finished. The manual pages are in $(BUILDDIR)/$(BUILDER)."
151-
152-
.PHONY: changes
153-
changes: BUILDER = changes
154-
changes: html
155-
156-
.PHONY: linkcheck
157-
linkcheck: BUILDER = linkcheck
158-
linkcheck: html
159-
@echo
160-
@echo "Link check complete; look for any errors in the above output " \
161-
"or in $(BUILDDIR)/$(BUILDER)/output.txt."
162-
163-
.PHONY: doctest
164-
doctest: BUILDER = doctest
165-
doctest: html
166-
@echo "Testing of doctests in the sources finished, look at the " \
167-
"results in $(BUILDDIR)/$(BUILDER)/output.txt."
168-
16967
.PHONY: htmlview
17068
htmlview: html
17169
$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('_build/html/index.html'))"
@@ -198,15 +96,17 @@ _ensure-pre-commit:
19896
lint: _ensure-pre-commit
19997
$(VENVDIR)/bin/python3 -m pre_commit run --all-files
20098

201-
include/branches.csv: include/release-cycle.json
202-
$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py
203-
204-
include/end-of-life.csv: include/release-cycle.json
205-
$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py
99+
# Defined so that "include/release-cycle.json"
100+
# doesn't fall through to the catch-all target.
101+
include/release-cycle.json:
102+
@exit
206103

207-
include/release-cycle.svg: include/release-cycle.json
104+
$(_RELEASE_CYCLE): include/release-cycle.json
208105
$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py
209-
210-
.PHONY: versions
211-
versions: venv include/branches.csv include/end-of-life.csv include/release-cycle.svg
212106
@echo Release cycle data generated.
107+
108+
# Catch-all target: route all unknown targets to Sphinx using the new
109+
# "make mode" option.
110+
.PHONY: Makefile
111+
%: Makefile ensure-venv $(_RELEASE_CYCLE)
112+
$(SPHINXBUILD) -M $@ "." "$(BUILDDIR)" $(_ALL_SPHINX_OPTS)

‎make.bat‎

Lines changed: 28 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -10,23 +10,9 @@ if "%PYTHON%" == "" (
1010
set PYTHON=py -3
1111
)
1212

13-
if not defined SPHINXLINT (
14-
%PYTHON% -c "import sphinxlint" > nul 2> nul
15-
if errorlevel 1 (
16-
echo Installing sphinx-lint with %PYTHON%
17-
rem Should have been installed with Sphinx earlier
18-
%PYTHON% -m pip install "sphinx-lint<1"
19-
if errorlevel 1 exit /B
20-
)
21-
set SPHINXLINT=%PYTHON% -m sphinxlint
22-
)
23-
2413
set BUILDDIR=_build
25-
set SPHINXOPTS=-W --keep-going --nitpicky
26-
set ALLSPHINXOPTS=--doctree-dir %BUILDDIR%/doctrees %SPHINXOPTS% .
27-
if NOT "%PAPER%" == "" (
28-
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
29-
)
14+
set SPHINXOPTS=--fail-on-warning --keep-going
15+
set _ALL_SPHINX_OPTS=%SPHINXOPTS%
3016

3117
if "%1" == "check" goto check
3218

@@ -60,6 +46,14 @@ if "%1" == "clean" (
6046
goto end
6147
)
6248

49+
if "%1" == "versions" (
50+
%PYTHON% _tools/generate_release_cycle.py
51+
if errorlevel 1 exit /b 1
52+
echo.
53+
echo Release cycle data generated.
54+
goto end
55+
)
56+
6357
rem Targets other than "clean", "check", "help", or "" need the
6458
rem Sphinx build command, which the user may define via SPHINXBUILD.
6559

@@ -75,157 +69,37 @@ if not defined SPHINXBUILD (
7569
set SPHINXBUILD=venv\Scripts\sphinx-build
7670
)
7771

78-
if "%1" == "html" (
79-
%SPHINXBUILD% --builder html %ALLSPHINXOPTS% %BUILDDIR%/html
80-
if errorlevel 1 exit /b 1
81-
echo.
82-
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
83-
goto end
84-
)
85-
8672
if "%1" == "htmlview" (
87-
cmd /C %this% html
88-
89-
if EXIST "%BUILDDIR%\html\index.html" (
90-
echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
91-
start "" "%BUILDDIR%\html\index.html"
92-
)
93-
94-
goto end
95-
)
96-
97-
if "%1" == "dirhtml" (
98-
%SPHINXBUILD% --builder dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
99-
if errorlevel 1 exit /b 1
100-
echo.
101-
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
102-
goto end
103-
)
104-
105-
if "%1" == "singlehtml" (
106-
%SPHINXBUILD% --builder singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
107-
if errorlevel 1 exit /b 1
108-
echo.
109-
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
110-
goto end
111-
)
112-
113-
if "%1" == "pickle" (
114-
%SPHINXBUILD% --builder pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
115-
if errorlevel 1 exit /b 1
116-
echo.
117-
echo.Build finished; now you can process the pickle files.
118-
goto end
119-
)
120-
121-
if "%1" == "json" (
122-
%SPHINXBUILD% --builder json %ALLSPHINXOPTS% %BUILDDIR%/json
123-
if errorlevel 1 exit /b 1
124-
echo.
125-
echo.Build finished; now you can process the JSON files.
126-
goto end
127-
)
128-
129-
if "%1" == "htmlhelp" (
130-
%SPHINXBUILD% --builder htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
131-
if errorlevel 1 exit /b 1
132-
echo.
133-
echo.Build finished; now you can run HTML Help Workshop with the ^
134-
.hhp project file in %BUILDDIR%/htmlhelp.
135-
goto end
136-
)
137-
138-
if "%1" == "qthelp" (
139-
%SPHINXBUILD% --builder qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
140-
if errorlevel 1 exit /b 1
141-
echo.
142-
echo.Build finished; now you can run "qcollectiongenerator" with the ^
143-
.qhcp project file in %BUILDDIR%/qthelp, like this:
144-
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PythonDevelopersGuide.qhcp
145-
echo.To view the help file:
146-
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PythonDevelopersGuide.ghc
147-
goto end
148-
)
149-
150-
if "%1" == "devhelp" (
151-
%SPHINXBUILD% --builder devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
152-
if errorlevel 1 exit /b 1
153-
echo.
154-
echo.Build finished.
155-
goto end
156-
)
157-
158-
if "%1" == "epub" (
159-
%SPHINXBUILD% --builder epub %ALLSPHINXOPTS% %BUILDDIR%/epub
160-
if errorlevel 1 exit /b 1
161-
echo.
162-
echo.Build finished. The epub file is in %BUILDDIR%/epub.
163-
goto end
164-
)
165-
166-
if "%1" == "latex" (
167-
%SPHINXBUILD% --builder latex %ALLSPHINXOPTS% %BUILDDIR%/latex
168-
if errorlevel 1 exit /b 1
169-
echo.
170-
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
171-
goto end
172-
)
73+
cmd /C %this% html
17374

174-
if "%1" == "text" (
175-
%SPHINXBUILD% --builder text %ALLSPHINXOPTS% %BUILDDIR%/text
176-
if errorlevel 1 exit /b 1
177-
echo.
178-
echo.Build finished. The text files are in %BUILDDIR%/text.
179-
goto end
180-
)
181-
182-
if "%1" == "man" (
183-
%SPHINXBUILD% --builder man %ALLSPHINXOPTS% %BUILDDIR%/man
184-
if errorlevel 1 exit /b 1
185-
echo.
186-
echo.Build finished. The manual pages are in %BUILDDIR%/man.
187-
goto end
188-
)
75+
if EXIST "%BUILDDIR%\html\index.html" (
76+
echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
77+
start "" "%BUILDDIR%\html\index.html"
78+
)
18979

190-
if "%1" == "changes" (
191-
%SPHINXBUILD% --builder changes %ALLSPHINXOPTS% %BUILDDIR%/changes
192-
if errorlevel 1 exit /b 1
193-
echo.
194-
echo.The overview file is in %BUILDDIR%/changes.
19580
goto end
19681
)
19782

198-
if "%1" == "linkcheck" (
199-
%SPHINXBUILD% --builder linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
200-
if errorlevel 1 exit /b 1
201-
echo.
202-
echo.Link check complete; look for any errors in the above output ^
203-
or in %BUILDDIR%/linkcheck/output.txt.
204-
goto end
205-
)
83+
%SPHINXBUILD% -M %1 "." %BUILDDIR% %_ALL_SPHINX_OPTS%
84+
goto end
20685

207-
if "%1" == "doctest" (
208-
%SPHINXBUILD% --builder doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
209-
if errorlevel 1 exit /b 1
210-
echo.
211-
echo.Testing of doctests in the sources finished, look at the ^
212-
results in %BUILDDIR%/doctest/output.txt.
213-
goto end
86+
:check
87+
if not defined SPHINXLINT (
88+
rem If it is not defined, we build in a virtual environment
89+
if not exist venv (
90+
echo. Setting up the virtual environment
91+
%PYTHON% -m venv venv
92+
echo. Installing requirements
93+
venv\Scripts\python -m pip install -r requirements.txt
94+
)
95+
set PYTHON=venv\Scripts\python
96+
set SPHINXLINT=%PYTHON% -m sphinxlint
21497
)
21598

216-
:check
21799
rem Ignore the tools and venv dirs and check that the default role is not used.
218100
cmd /S /C "%SPHINXLINT% -i tools -i venv --enable default-role"
219101
goto end
220102

221-
if "%1" == "versions" (
222-
%PYTHON% _tools/generate_release_cycle.py
223-
if errorlevel 1 exit /b 1
224-
echo.
225-
echo Release cycle data generated.
226-
goto end
227-
)
228-
229103
:end
230104
popd
231105
endlocal

0 commit comments

Comments
 (0)