Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use "modern" Makefile template #1370

Merged
merged 8 commits into from
Aug 15, 2024
Merged

Use "modern" Makefile template #1370

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
17a60fa
Use "modern" Makefile template
AA-Turner Aug 14, 2024
2995bf1
Terminal?
AA-Turner Aug 14, 2024
f914b22
Phony
AA-Turner Aug 14, 2024
2178e09
No PHONY
AA-Turner Aug 14, 2024
986b68c
make.bat also exists...
AA-Turner Aug 14, 2024
09cdf3c
Powershell
AA-Turner Aug 14, 2024
9cc226b
Remove -q
AA-Turner Aug 14, 2024
b690c8a
Remove obsolete help
AA-Turner Aug 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 17 additions & 117 deletions Makefile
View file
Open in desktop
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."
AA-Turner marked this conversation as resolved.
Show resolved Hide resolved

.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
Open in desktop
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
Loading