Skip to content

Commit

Permalink
dev: Use stricter Sphinx builds
Browse files Browse the repository at this point in the history
Catches warnings earlier during local builds, instead of only during CI.

sphinx-autobuild doesn't have a released version which supports
--keep-going¹, so be a little looser there.

These options aren't the default for SPHINXOPTS so that that variable
may still be used for passing additional options without unintentionally
(and unnecessarily) overriding the strictures.

¹ <sphinx-doc/sphinx-autobuild#133>
  • Loading branch information
tsibley committed Jul 19, 2023
1 parent 4ad5e8e commit a9d0980
Showing 1 changed file with 10 additions and 2 deletions.
12 changes: 10 additions & 2 deletions doc/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@ SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build

# Require stricter builds with
# -n: warn on missing references
# -W: error on warnings
# --keep-going: find all warnings
# https://www.sphinx-doc.org/en/master/man/sphinx-build.html
STRICT = -n -W --keep-going
LOOSE = -n

GENERATE = ../devel/generate-command-doc

# Put it first so that "make" without argument is like "make help".
Expand All @@ -21,7 +29,7 @@ help:
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
if [[ $@ != clean ]]; then $(GENERATE); fi
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(STRICT) $(SPHINXOPTS) $(O)

HOST ?= 127.0.0.1
PORT ?= 8000
Expand All @@ -30,4 +38,4 @@ serve: dirhtml
cd "$(BUILDDIR)/dirhtml" && python3 -m http.server --bind "$(HOST)" "$(PORT)"

livehtml:
sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)/dirhtml" --host "$(HOST)" --port "$(PORT)" --watch ../nextstrain/cli --pre-build "$(GENERATE)" $(SPHINXOPTS) $(O)
sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)/dirhtml" --host "$(HOST)" --port "$(PORT)" --watch ../nextstrain/cli --pre-build "$(GENERATE)" $(LOOSE) $(SPHINXOPTS) $(O)

0 comments on commit a9d0980

Please sign in to comment.