Skip to content

Docs: Move .PHONY to each section to avoid copy/paste omissions #99396

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 1 commit into from
Nov 27, 2022
Merged
Changes from all commits
Commits
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
28 changes: 24 additions & 4 deletions Doc/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,7 @@ PAPEROPT_letter = -D latex_elements.papersize=letterpaper
ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees $(PAPEROPT_$(PAPER)) -j auto \
$(SPHINXOPTS) $(SPHINXERRORHANDLING) . build/$(BUILDER) $(SOURCES)

.PHONY: help build html htmlhelp latex text texinfo epub changes linkcheck \
coverage doctest pydoc-topics htmlview clean clean-venv venv dist check serve \
autobuild-dev autobuild-dev-html autobuild-stable autobuild-stable-html

.PHONY: help
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " clean to remove build files"
Expand All @@ -44,6 +41,7 @@ help:
@echo " dist to create a \"dist\" directory with archived docs for download"
@echo " check to run a check for frequent markup errors"

.PHONY: build
build:
-mkdir -p build
# Look first for a Misc/NEWS file (building from a source release tarball
Expand All @@ -70,70 +68,85 @@ build:
$(SPHINXBUILD) $(ALLSPHINXOPTS)
@echo

.PHONY: html
html: BUILDER = html
html: build
@echo "Build finished. The HTML pages are in build/html."

.PHONY: htmlhelp
htmlhelp: BUILDER = htmlhelp
htmlhelp: build
@echo "Build finished; now you can run HTML Help Workshop with the" \
"build/htmlhelp/pydoc.hhp project file."

.PHONY: latex
latex: BUILDER = latex
latex: build
@echo "Build finished; the LaTeX files are in build/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."

.PHONY: text
text: BUILDER = text
text: build
@echo "Build finished; the text files are in build/text."

.PHONY: texinfo
texinfo: BUILDER = texinfo
texinfo: build
@echo "Build finished; the python.texi file is in build/texinfo."
@echo "Run \`make info' in that directory to run it through makeinfo."

.PHONY: epub
epub: BUILDER = epub
epub: build
@echo "Build finished; the epub files are in build/epub."

.PHONY: changes
changes: BUILDER = changes
changes: build
@echo "The overview file is in build/changes."

.PHONY: linkcheck
linkcheck: BUILDER = linkcheck
linkcheck:
@$(MAKE) build BUILDER=$(BUILDER) || { \
echo "Link check complete; look for any errors in the above output" \
"or in build/$(BUILDER)/output.txt"; \
false; }

.PHONY: coverage
coverage: BUILDER = coverage
coverage: build
@echo "Coverage finished; see c.txt and python.txt in build/coverage"

.PHONY: doctest
doctest: BUILDER = doctest
doctest:
@$(MAKE) build BUILDER=$(BUILDER) || { \
echo "Testing of doctests in the sources finished, look at the" \
"results in build/doctest/output.txt"; \
false; }

.PHONY: pydoc-topics
pydoc-topics: BUILDER = pydoc-topics
pydoc-topics: build
@echo "Building finished; now run this:" \
"cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py"

.PHONY: htmlview
htmlview: html
$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"

.PHONY: clean
clean: clean-venv
-rm -rf build/*

.PHONY: clean-venv
clean-venv:
rm -rf $(VENVDIR)

.PHONY: venv
venv:
@if [ -d $(VENVDIR) ] ; then \
echo "venv already exists."; \
Expand All @@ -145,6 +158,7 @@ venv:
echo "The venv has been created in the $(VENVDIR) directory"; \
fi

.PHONY: dist
dist:
rm -rf dist
mkdir -p dist
Expand Down Expand Up @@ -199,12 +213,14 @@ dist:
rm -r dist/python-$(DISTVERSION)-docs-texinfo
rm dist/python-$(DISTVERSION)-docs-texinfo.tar

.PHONY: check
check:
# Check the docs and NEWS files with sphinx-lint.
# Ignore the tools and venv dirs and check that the default role is not used.
$(SPHINXLINT) -i tools -i $(VENVDIR) --enable default-role
$(SPHINXLINT) --enable default-role ../Misc/NEWS.d/next/

.PHONY: serve
serve:
@echo "The serve target was removed, use htmlview instead (see bpo-36329)"

Expand All @@ -216,22 +232,26 @@ serve:
# output files)

# for development releases: always build
.PHONY: autobuild-dev
autobuild-dev:
make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'

# for quick rebuilds (HTML only)
.PHONY: autobuild-dev-html
autobuild-dev-html:
make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'

# for stable releases: only build if not in pre-release stage (alpha, beta)
# release candidate downloads are okay, since the stable tree can be in that stage
.PHONY: autobuild-stable
autobuild-stable:
@case $(DISTVERSION) in *[ab]*) \
echo "Not building; $(DISTVERSION) is not a release version."; \
exit 1;; \
esac
@make autobuild-dev

.PHONY: autobuild-stable-html
autobuild-stable-html:
@case $(DISTVERSION) in *[ab]*) \
echo "Not building; $(DISTVERSION) is not a release version."; \
Expand Down