> Why are we pinning to 1.8.2 when the official docs builds for all releases are currently using 2.3.1?  (see, for example, https://docs.python.org/3.8/ at bottom right corner)

First of all, to repair the CI :-) Before my change, it was no longer possible to merge any change in 3.8! (I didn't check for 3.7, but I expect that it wasn't possible neither).

Second, 1.8.2 version comes from the CI configuration:

$ grep -i sphinx== .travis.yml .azure-pipelines/* Doc/Makefile 
.travis.yml:        - python -m pip install sphinx==1.8.2 blurb
.azure-pipelines/docs-steps.yml:- script: python -m pip install sphinx==1.8.2 blurb python-docs-theme
Doc/Makefile:	$(VENVDIR)/bin/python3 -m pip install -U Sphinx==1.8.2 blurb

If Sphinx version is changed in Doc/Makefile, I would prefer to also update the version in the CI configuration.

I also vaguely recall discussions about issues with newer Sphinx. I don't recall if it was 2.0 or another version. Julien Palard may recall that better than me! Was it bpo-35472?

--

I don't really care of the Sphinx version, I only care about working CI and consistency between all pinned versions ;-)

--

By the way, maybe Doc/Makefile could use the latest Sphinx version by default, and the Python CI could use a pinned version. The problem is that the Sphinx version cannot be configured currently when running "make venv".

Oh, .travis.yml is differecen between 3.7 and 3.8.

3.8 and master use "make -C Doc/ PYTHON=../python venv".

3.7 doesn't use "make venv" but:

  before_script:
    - cd Doc
    # Sphinx is pinned so that new versions that introduce new warnings won't suddenly cause build failures.
    # (Updating the version is fine as long as no warnings are raised by doing so.)
    - python -m pip install sphinx==1.8.2 blurb
  script:
    - make check suspicious html SPHINXOPTS="-q -W -j4"


Maybe 3.7 should mimick what is done in 3.8 and master to ease maintenance. I don't know.