Repository navigation
Commit f094909
committed
Add BUILDDIR var to doc/Makefile; have tox use it
This adds BUILDDIR as a variable in the documentation generation
makefile that, along SPHINXOPTS, SPHINXBUILD, and PAPER, defaults
to the usual best value but can be set when invoking make.
The main use for choosing a different build output directory is to
test building without overwriting or otherwise interfering with any
files from a build one may really want to use. tox.ini is thus
modified to pass a path pointing inside its temporary directory as
BUILDDIR, so the "html" tox environment now makes no changes
outside the .tox directory. This is thus suitable for being run
automatically, so the "html" environment is now in the envlist.1 parent 6de86a8 commit f094909
2 files changed
Lines changed: 26 additions & 25 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -2,14 +2,15 @@ | |||
| 2 | 2 | # | |
| 3 | 3 | ||
| 4 | 4 | # You can set these variables from the command line. | |
| 5 | + BUILDDIR = build | ||
| 5 | 6 | SPHINXOPTS = -W | |
| 6 | 7 | SPHINXBUILD = sphinx-build | |
| 7 | 8 | PAPER = | |
| 8 | 9 | ||
| 9 | 10 | # Internal variables. | |
| 10 | 11 | PAPEROPT_a4 = -D latex_paper_size=a4 | |
| 11 | 12 | PAPEROPT_letter = -D latex_paper_size=letter | |
| 12 | - ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source | ||
| 13 | + ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source | ||
| 13 | 14 | ||
| 14 | 15 | .PHONY: help clean html web pickle htmlhelp latex changes linkcheck | |
| 15 | 16 | ||
@@ -24,52 +25,52 @@ help: | |||
| 24 | 25 | @echo " linkcheck to check all external links for integrity" | |
| 25 | 26 | ||
| 26 | 27 | clean: | |
| 27 | - -rm -rf build/* | ||
| 28 | + -rm -rf $(BUILDDIR)/* | ||
| 28 | 29 | ||
| 29 | 30 | html: | |
| 30 | - mkdir -p build/html build/doctrees | ||
| 31 | - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html | ||
| 31 | + mkdir -p $(BUILDDIR)/html $(BUILDDIR)/doctrees | ||
| 32 | + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html | ||
| 32 | 33 | @echo | |
| 33 | - @echo "Build finished. The HTML pages are in build/html." | ||
| 34 | + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." | ||
| 34 | 35 | ||
| 35 | 36 | pickle: | |
| 36 | - mkdir -p build/pickle build/doctrees | ||
| 37 | - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle | ||
| 37 | + mkdir -p $(BUILDDIR)/pickle $(BUILDDIR)/doctrees | ||
| 38 | + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle | ||
| 38 | 39 | @echo | |
| 39 | 40 | @echo "Build finished; now you can process the pickle files." | |
| 40 | 41 | ||
| 41 | 42 | web: pickle | |
| 42 | 43 | ||
| 43 | 44 | json: | |
| 44 | - mkdir -p build/json build/doctrees | ||
| 45 | - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json | ||
| 45 | + mkdir -p $(BUILDDIR)/json $(BUILDDIR)/doctrees | ||
| 46 | + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json | ||
| 46 | 47 | @echo | |
| 47 | 48 | @echo "Build finished; now you can process the JSON files." | |
| 48 | 49 | ||
| 49 | 50 | htmlhelp: | |
| 50 | - mkdir -p build/htmlhelp build/doctrees | ||
| 51 | - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp | ||
| 51 | + mkdir -p $(BUILDDIR)/htmlhelp $(BUILDDIR)/doctrees | ||
| 52 | + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp | ||
| 52 | 53 | @echo | |
| 53 | 54 | @echo "Build finished; now you can run HTML Help Workshop with the" \ | |
| 54 | - ".hhp project file in build/htmlhelp." | ||
| 55 | + ".hhp project file in $(BUILDDIR)/htmlhelp." | ||
| 55 | 56 | ||
| 56 | 57 | latex: | |
| 57 | - mkdir -p build/latex build/doctrees | ||
| 58 | - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex | ||
| 58 | + mkdir -p $(BUILDDIR)/latex $(BUILDDIR)/doctrees | ||
| 59 | + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex | ||
| 59 | 60 | @echo | |
| 60 | - @echo "Build finished; the LaTeX files are in build/latex." | ||
| 61 | + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." | ||
| 61 | 62 | @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ | |
| 62 | 63 | "run these through (pdf)latex." | |
| 63 | 64 | ||
| 64 | 65 | changes: | |
| 65 | - mkdir -p build/changes build/doctrees | ||
| 66 | - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes | ||
| 66 | + mkdir -p $(BUILDDIR)/changes $(BUILDDIR)/doctrees | ||
| 67 | + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes | ||
| 67 | 68 | @echo | |
| 68 | - @echo "The overview file is in build/changes." | ||
| 69 | + @echo "The overview file is in $(BUILDDIR)/changes." | ||
| 69 | 70 | ||
| 70 | 71 | linkcheck: | |
| 71 | - mkdir -p build/linkcheck build/doctrees | ||
| 72 | - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck | ||
| 72 | + mkdir -p $(BUILDDIR)/linkcheck $(BUILDDIR)/doctrees | ||
| 73 | + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | ||
| 73 | 74 | @echo | |
| 74 | 75 | @echo "Link check complete; look for any errors in the above output " \ | |
| 75 | - "or in build/linkcheck/output.txt." | ||
| 76 | + "or in $(BUILDDIR)/linkcheck/output.txt." | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1,6 +1,6 @@ | |||
| 1 | 1 | [tox] | |
| 2 | 2 | requires = tox>=4 | |
| 3 | - env_list = py{37,38,39,310,311,312}, lint, mypy | ||
| 3 | + env_list = py{37,38,39,310,311,312}, lint, mypy, html | ||
| 4 | 4 | ||
| 5 | 5 | [testenv] | |
| 6 | 6 | description = Run unit tests | |
@@ -22,11 +22,11 @@ base_python = py39 | |||
| 22 | 22 | commands = mypy -p git | |
| 23 | 23 | ignore_outcome = true | |
| 24 | 24 | ||
| 25 | - # Run "tox -e html" for this. It is deliberately excluded from env_list, as | ||
| 26 | - # unlike the other environments, this one writes outside the .tox/ directory. | ||
| 27 | 25 | [testenv:html] | |
| 28 | 26 | description = Build HTML documentation | |
| 29 | 27 | base_python = py39 | |
| 30 | 28 | deps = -r doc/requirements.txt | |
| 31 | 29 | allowlist_externals = make | |
| 32 | - commands = make -C doc html | ||
| 30 | + commands = | ||
| 31 | + make BUILDDIR={env_tmp_dir}/doc/build -C doc clean | ||
| 32 | + make BUILDDIR={env_tmp_dir}/doc/build -C doc html | ||
0 commit comments