Upgrade version of Sphinx for docs

[brainwane]

When I visit https://pip.pypa.io/en/latest/ , I see that it was "Created using Sphinx 2.4.3." That version was released in February and bugfixes/features since then include faster builds and various improvements to the HTML themes. Shall we upgrade?

I imagine the first step would be for someone to locally try out the upgrade, check that the docs still build fine, and skim the docs to check for rendering problems.

[uranusjr]

Tagging @maxwell-k since we talked about this during the EuroPython sprint and IORC you had some interest in looking into this.

[shireenrao]

Was working on a different PR for docs, so did a quick check. So far see two issues which are causing the build to fail

• configuration-files.rst - Fails
  • pip/docs/html/development/architecture/configuration-files.rst:111:duplicate object description of Configuration, other instance in development/architecture/configuration-files, use :noindex: for one of them
  • Adding :noindex: to the second Configuration class definition fixes this
• installing.rst, pip_install.rst - intersphinx_mapping linking to pypug is breaking with the following error
  • pip/docs/html/installing.rst:40:term not in glossary: pypug:Source Distribution (or "sdist")
  • pip/docs/html/reference/pip_install.rst:247:term not in glossary: pypug:Requirement Specifier

[shireenrao]

All the intersphinx_mapping links are now case sensitive.

:term:source distributions <pypug:Source Distribution (or "sdist")>
worked after changing to
:term:source distributions <pypug:source distribution (or "sdist")>

Once I fixed the case by looking at how python -msphinx.ext.intersphinx https://packaging.python.org/objects.inv lists these names, the build succeeds.

[shireenrao]

Sorry - Didn't realize this issue was taken. I had started looking at this when @brainwane first posted the issue just out of curiosity.

[brainwane]

@shireenrao please feel free to look at other https://github.com/pypa/ projects that use Read The Docs & Sphinx, and see whether any of them could use a Sphinx version upgrade! :-)

[shireenrao]

If nobody is working on this, can I submit a PR?

[brainwane]

@pradyunsg You've been working on our Sphinx usage a lot lately; anything here in this issue that still needs doing?

[pradyunsg]

Not really. We'd probably bump to 3.4 in the next few days, but that's a very different thing compared to Sphinx 2 vs Sphinx 3 that we had to do here. :)