Actually cpython adds both -W and --keep-goingin .github/workflows/doc.yml, and -W in cpython/Doc/Makefile.

Is there any downside in adding them both directly to the Makefile?

Is there any downside in adding them both directly to the Makefile?

Users' local builds will fail slower, but they can Ctrl-C them anyway if they want and I'd still rather have the full error output, especially for something that only takes a few seconds to build like the devguide.

Can we add -n too

Ok.

Is there a reason we can't add it to the existing SPHINXOPTS variable instead of making a new bespoke SPHINXERRORHANDLING one

The only reason is to keep consistent with cpython/Doc/Makefile. Adding it directly to SPHINXOPTS (both here and in the cpython repo) is fine with me.

Wouldn't it make sense to add it to the make.bat too, so they are consistent?

I'll update it once we decide which options we want.

I noticed that line 227 in the conf.py contains an invalid escape sequence

I can fix this too.

It seems that -W was

• first added to ALLSPHINXOPTS by @tirkarthi
  • in bpo-34081: Fix wrong example link that was linking to distutils cpython#8248
  • to fix Sphinx duplicate label warning in docs cpython#78262
• then moved to SPHINXERRORHANDLING by @JulienPalard
  • in Doc: -W flag for sphinx-build can be disabled cpython#10303
  • to make it optional through make html SPHINXERRORHANDLING=''

Perhaps for cpython, having -W without --keep-going was desirable for local build but not for CI, hence the addition of a separate SPHINXERRORHANDLING. Note that cpython doesn't have SPHINXOPTS, and that it could be used instead of SPHINXERRORHANDLING, but if we change it on cpython for consistency we should make sure that CI is updated accordingly.

So the plan would be:

• set SPHINXOPTS = -W --keep-going -n and fix conf.py for this repo
• set SPHINXOPTS = -W and update CI for cpython (in a separate issue)

FWIW, in case of errors make htmlview will now bail after running the html target and won't open the browser. I don't know if this is something we can/want to fix.

I think it's fine to bail: it's a prompt to fix the (new) errors.

Anyone on Windows wants to check if the bat works? 🦇