Skip to content

Refactor docs Makefile #8933

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.

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

Merged
merged 11 commits into from
Apr 29, 2025
42 changes: 18 additions & 24 deletions docs/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,23 @@

# You can set these variables from the command line.
PYTHON = python3
SPHINXOPTS =
SPHINXBUILD = $(PYTHON) -m sphinx.cmd.build
PAPER =
SPHINXOPTS = --fail-on-warning
BUILDDIR = _build
BUILDER = html
JOBS = auto
PAPER =

# Internal variables.
PAPEROPT_a4 = --define latex_paper_size=a4
PAPEROPT_letter = --define latex_paper_size=letter
ALLSPHINXOPTS = --doctree-dir $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, right, I18NSPHINXOPTS is unused due to #8917


ALLSPHINXOPTS = --builder $(BUILDER) \
--doctree-dir $(BUILDDIR)/doctrees \
--jobs $(JOBS) \
$(PAPEROPT_$(PAPER)) \
$(SPHINXOPTS) \
. $(BUILDDIR)/$(BUILDER)

.PHONY: help
help:
Expand All @@ -36,31 +42,19 @@ install-sphinx:
.PHONY: html
html:
$(MAKE) install-sphinx
$(SPHINXBUILD) --builder html --fail-on-warning --keep-going $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
$(SPHINXBUILD) $(ALLSPHINXOPTS)

.PHONY: dirhtml
dirhtml:
$(MAKE) install-sphinx
$(SPHINXBUILD) --builder dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
dirhtml: BUILDER = dirhtml
dirhtml: html

.PHONY: singlehtml
singlehtml:
$(MAKE) install-sphinx
$(SPHINXBUILD) --builder singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
singlehtml: BUILDER = singlehtml
singlehtml: html

.PHONY: linkcheck
linkcheck:
$(MAKE) install-sphinx
$(SPHINXBUILD) --builder linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck -j auto
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
linkcheck: BUILDER = linkcheck
linkcheck: html

.PHONY: htmlview
htmlview: html
Expand Down
2 changes: 0 additions & 2 deletions docs/make.bat
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,8 @@ if "%SPHINXBUILD%" == "" (
)
set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)

if "%1" == "" goto help
Expand Down