How to get sphinx-autobuild to be nitpicky **and** keep going?

Documentation
1

I’d like my running make htmllive instance to process changed files in nitpicky mode. If I add -n to SPHINXOPTS it stops after finding a single problem (warnings converted to errors). If I add --keep-going to SPHINXOPTS it complains that it’s an unknown command line arg:

./venv/bin/sphinx-autobuild -b html -d build/doctrees -j auto  -n --keep-going --re-ignore="/venv/" --open-browser --delay 0 -W . build/html 
usage: sphinx-autobuild [-h] [--port PORT] [--host HOST] [--re-ignore RE_IGNORE]
                        [--ignore IGNORE] [--no-initial] [--open-browser] [--delay DELAY]
                        [--watch DIR] [--pre-build COMMAND] [--version]
                        sourcedir outdir [filenames ...]
sphinx-autobuild: error: unrecognized arguments: --keep-going
make: *** [build] Error 2

I see ("-keep-going", None), in build.SPHINX_BUILD_OPTIONS. What am I missing?

2

Only certain options are passed on to sphinx. They are listed here: sphinx-autobuild · PyPI

--keep-going is not one of them.

3

Thanks. I thought SPHINX_BUILD_OPTIONS controlled that. Supporting -n but not --keep-going for a long running server seems somewhat suboptimal to me.

2 Likes
4

Doing a bit of digging, I see this issue was fixed in the main branch of sphinx-autobuild, but as of yet there hasn’t been a release to PyPI since. You could either wait for one, ping a maintainer, or install it from GitHub in the meantime.

5

I think I understand what’s going on. The current release is 2021.03.14. --keep-going was added to the SPHINX_BUILD_OPTIONS on 2022-12-24, so I should be able to build my own version.

1 Like
6

I sometimes use this:

make -C Doc htmllive SPHINXERRORHANDLING=-n

It shows warnings, and completes the build, rebuilding on changes.

And if I just want to rebuild a single file, to make it quicker:

make -C Doc htmllive SPHINXERRORHANDLING=-n SOURCES=whatsnew/2.6.rst
1 Like
7

My goal is to have make htmllive running, edit a file and have it rechecked without crashing the running sphinx-autobuild.

I believe I’ve figured things out. Whatever work the sphinx-autobuild code does to process args doesn’t accommodate long form command line args like --keep-going. My solution for now was to add a -k flag to sphinx proper and specify 'k' in SPHINX_BUILD_OPTIONS. I thought sphinx-autobuild would just reprocess the changed file, but it appears to process everything all over again. Despite the fact that my change keeps things going, it’s not as helpful as I thought it would be.

8

I should have thought of it before, but couldn’t you just not use -W? Warnings are still displayed but don’t error…which is what you want, right?

9

I didn’t notice -W in the default list of Sphinx args. Does -n imply -W? (Not near my computer at the moment to check.)

10

Nope, as non-nitpicky warnings are always emitted (at the default errorlevel), -n emits nitpicky warnings too, and -W makes all emitted warnings errors.

11

In front of a computer, I dug into this a bit… The cpython/Doc/Makefile has a couple different SPHINX-related variable settings, not next to one another:

SPHINXERRORHANDLING = -n

Then later one for the htmllive target:

htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
htmllive: SPHINXOPTS = -k --re-ignore="/venv/" --open-browser --delay 0
htmllive: html

My usual first glance at a Makefile involves the target of interest. I saw SPHINXOPTS, but didn’t think to look any farther for more ways to tweak the sphinx-build command.