Skip to content

Commit

Permalink
Modernise the make templates (python#1370)
Browse files Browse the repository at this point in the history
  • Loading branch information
@AA-Turner
AA-Turner authored Aug 15, 2024
1 parent 9447a88 commit cedcb49
Show file tree
Hide file tree
Showing 3 changed files with 144 additions and 271 deletions.
134 changes: 17 additions & 117 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,50 +10,31 @@ SPHINXOPTS = --fail-on-warning --keep-going
BUILDDIR = _build
BUILDER = html
JOBS = auto
PAPER =
SPHINXLINT = $(VENVDIR)/bin/sphinx-lint
REQUIREMENTS = requirements.txt

# Internal variables.
PAPEROPT_a4 = --define latex_paper_size=a4
PAPEROPT_letter = --define latex_paper_size=letter
ALLSPHINXOPTS = --builder $(BUILDER) \
--doctree-dir $(BUILDDIR)/doctrees \
--jobs $(JOBS) \
$(PAPEROPT_$(PAPER)) \
$(SPHINXOPTS) \
. $(BUILDDIR)/$(BUILDER)
_ALL_SPHINX_OPTS = --jobs $(JOBS) $(SPHINXOPTS)
_RELEASE_CYCLE = include/branches.csv \
include/end-of-life.csv \
include/release-cycle.svg

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

.PHONY: clean
clean: clean-venv
-rm -rf $(BUILDDIR)/*
-rm -rf $(_RELEASE_CYCLE)

.PHONY: clean-venv
clean-venv:
Expand Down Expand Up @@ -83,89 +64,6 @@ ensure-venv:
echo "The venv has been created in the $(VENVDIR) directory"; \
fi

.PHONY: html
html: ensure-venv versions
$(SPHINXBUILD) $(ALLSPHINXOPTS)

.PHONY: dirhtml
dirhtml: BUILDER = dirhtml
dirhtml: html

.PHONY: singlehtml
singlehtml: BUILDER = singlehtml
singlehtml: html

.PHONY: pickle
pickle: BUILDER = pickle
pickle: html
@echo
@echo "Build finished; now you can process the pickle files."

.PHONY: json
json: BUILDER = json
json: html
@echo
@echo "Build finished; now you can process the JSON files."

.PHONY: htmlhelp
htmlhelp: BUILDER = htmlhelp
htmlhelp: html
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/$(BUILDER)."

.PHONY: qthelp
qthelp: BUILDER = qthelp
qthelp: html

.PHONY: devhelp
devhelp: BUILDER = devhelp
devhelp: html

.PHONY: epub
epub: BUILDER = epub
epub: html
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/$(BUILDER)."

.PHONY: latex
latex: BUILDER = latex
latex: html

.PHONY: latexpdf
latexpdf: BUILDER = latex
latexpdf: html
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/$(BUILDER)."

.PHONY: text
text: BUILDER = text
text: html

.PHONY: man
man: BUILDER = man
man: html
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/$(BUILDER)."

.PHONY: changes
changes: BUILDER = changes
changes: html

.PHONY: linkcheck
linkcheck: BUILDER = linkcheck
linkcheck: html
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/$(BUILDER)/output.txt."

.PHONY: doctest
doctest: BUILDER = doctest
doctest: html
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/$(BUILDER)/output.txt."

.PHONY: htmlview
htmlview: html
$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('_build/html/index.html'))"
Expand Down Expand Up @@ -198,15 +96,17 @@ _ensure-pre-commit:
lint: _ensure-pre-commit
$(VENVDIR)/bin/python3 -m pre_commit run --all-files

include/branches.csv: include/release-cycle.json
$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py

include/end-of-life.csv: include/release-cycle.json
$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py
# Defined so that "include/release-cycle.json"
# doesn't fall through to the catch-all target.
include/release-cycle.json:
@exit

include/release-cycle.svg: include/release-cycle.json
$(_RELEASE_CYCLE): include/release-cycle.json
$(VENVDIR)/bin/python3 _tools/generate_release_cycle.py

.PHONY: versions
versions: venv include/branches.csv include/end-of-life.csv include/release-cycle.svg
@echo Release cycle data generated.

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.
.PHONY: Makefile
%: Makefile ensure-venv $(_RELEASE_CYCLE)
$(SPHINXBUILD) -M $@ "." "$(BUILDDIR)" $(_ALL_SPHINX_OPTS)
182 changes: 28 additions & 154 deletions make.bat
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,23 +10,9 @@ if "%PYTHON%" == "" (
set PYTHON=py -3
)

if not defined SPHINXLINT (
%PYTHON% -c "import sphinxlint" > nul 2> nul
if errorlevel 1 (
echo Installing sphinx-lint with %PYTHON%
rem Should have been installed with Sphinx earlier
%PYTHON% -m pip install "sphinx-lint<1"
if errorlevel 1 exit /B
)
set SPHINXLINT=%PYTHON% -m sphinxlint
)

set BUILDDIR=_build
set SPHINXOPTS=-W --keep-going --nitpicky
set ALLSPHINXOPTS=--doctree-dir %BUILDDIR%/doctrees %SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
)
set SPHINXOPTS=--fail-on-warning --keep-going
set _ALL_SPHINX_OPTS=%SPHINXOPTS%

if "%1" == "check" goto check

Expand Down Expand Up @@ -60,6 +46,14 @@ if "%1" == "clean" (
goto end
)

if "%1" == "versions" (
%PYTHON% _tools/generate_release_cycle.py
if errorlevel 1 exit /b 1
echo.
echo Release cycle data generated.
goto end
)

rem Targets other than "clean", "check", "help", or "" need the
rem Sphinx build command, which the user may define via SPHINXBUILD.

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

if "%1" == "html" (
%SPHINXBUILD% --builder html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)

if "%1" == "htmlview" (
cmd /C %this% html

if EXIST "%BUILDDIR%\html\index.html" (
echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
start "" "%BUILDDIR%\html\index.html"
)

goto end
)

if "%1" == "dirhtml" (
%SPHINXBUILD% --builder dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)

if "%1" == "singlehtml" (
%SPHINXBUILD% --builder singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)

if "%1" == "pickle" (
%SPHINXBUILD% --builder pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)

if "%1" == "json" (
%SPHINXBUILD% --builder json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)

if "%1" == "htmlhelp" (
%SPHINXBUILD% --builder htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)

if "%1" == "qthelp" (
%SPHINXBUILD% --builder qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PythonDevelopersGuide.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PythonDevelopersGuide.ghc
goto end
)

if "%1" == "devhelp" (
%SPHINXBUILD% --builder devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)

if "%1" == "epub" (
%SPHINXBUILD% --builder epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)

if "%1" == "latex" (
%SPHINXBUILD% --builder latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
cmd /C %this% html

if "%1" == "text" (
%SPHINXBUILD% --builder text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)

if "%1" == "man" (
%SPHINXBUILD% --builder man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if EXIST "%BUILDDIR%\html\index.html" (
echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
start "" "%BUILDDIR%\html\index.html"
)

if "%1" == "changes" (
%SPHINXBUILD% --builder changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)

if "%1" == "linkcheck" (
%SPHINXBUILD% --builder linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
%SPHINXBUILD% -M %1 "." %BUILDDIR% %_ALL_SPHINX_OPTS%
goto end

if "%1" == "doctest" (
%SPHINXBUILD% --builder doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
:check
if not defined SPHINXLINT (
rem If it is not defined, we build in a virtual environment
if not exist venv (
echo. Setting up the virtual environment
%PYTHON% -m venv venv
echo. Installing requirements
venv\Scripts\python -m pip install -r requirements.txt
)
set PYTHON=venv\Scripts\python
set SPHINXLINT=%PYTHON% -m sphinxlint
)

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

if "%1" == "versions" (
%PYTHON% _tools/generate_release_cycle.py
if errorlevel 1 exit /b 1
echo.
echo Release cycle data generated.
goto end
)

:end
popd
endlocal
Loading

0 comments on commit cedcb49

Please sign in to comment.