Building the documentation confusion leads to error: no theme named 'python-docs-theme' found (missing theme.conf?)

[peterjpxie]

Documentation

After reading the devguide https://devguide.python.org/documentation/start-documenting/#building-the-documentation to build the documentation, I faced the very common error: no theme named 'python-docs-theme' found (missing theme.conf?).

(cpython) peter@xxx:~/repo/cpython/Doc$ sphinx-build -b html . build/html
Running Sphinx v4.3.2

Theme error:
no theme named 'python_docs_theme' found (missing theme.conf?)
(cpython) peter@xxx:~/repo/cpython/Doc$ which sphinx-build
/usr/bin/sphinx-build

The root cause is that sphinx is not installed in the virtual env where python-docs-theme is installed, as mentioned in python-docs-theme issue #45.

Full Steps to Reproduce:

Use ubuntu 22.04 or 16.04
apt-get install python3-sphinx # as per https://www.sphinx-doc.org/en/master/usage/installation.html#linux
<create a virtual env>
pip install blurb
pip install python-docs-theme
cd Doc
make html
or 
sphinx-build -b html . build/html

Of course, it works if you follow exactly this:

cd Doc
make venv
make html

Where does the confusion come from:
"You are expected to have installed the latest stable version of Sphinx and blurb on your system or in a virtualenv (which can be created using make venv), so that the Makefile can find the sphinx-build command. You can also specify the location of sphinx-build with the SPHINXBUILD make variable. "

1/ Sphinx This links to https://www.sphinx-doc.org and it provides installation steps apt-get install python3-sphinx which installs sphinx in system path /usr/bin/sphinx-build. It won't work with python-docs-theme installed in a virtualenv.

[Suggestion] Change the sphinx link to https://github.com/sphinx-doc/sphinx which provide install step pip install -U sphinx instead.

2/ "You can also specify the location of sphinx-build with the SPHINXBUILD make variable" => this also makes me think sphinx-build is okay to be anywhere, but it is not.

[CAM-Gerlach]

Thanks for the detailed report describing your experiences; it's very useful to understand what particular elements led to the resultant confusion. I can certainly see how that section is potentially confusing and difficult to follow to a new contributor (i.e. the primary target audience), as it lacks a clear, concrete, step by step structure, muddles minor or advanced details and elaboration with key basic information, and uses somewhat outdated language.

Furthermore, as you mentioned, it manually lists certain dependencies and states that they are required to be installed no less than three times (including twice in the intro paragraph), which is instead handled for the user automatically with make venv/running make.bat, and should be installed via the requirements.txt rather than manually ottherwise. Furthermore, it doesn't at least link to how to create and activate the necessary environment on Windows and non-make usage, nor state how to install the required dependencies or link to the canonical listing of them (in the requirements.txt).

I've opened PR #1038, which thoroughly overhauls this section to address all the above concerns. Please review it and let us know what you think!

1/ Sphinx This links to sphinx-doc.org and it provides installation steps apt-get install python3-sphinx which installs sphinx in system path /usr/bin/sphinx-build. It won't work with python-docs-theme installed in a virtualenv. Change the sphinx link to sphinx-doc/sphinx which provide install step pip install -U sphinx instead.

The make venv target and the make.bat batch script do this installation automatically, and otherwise the supported versions of all of the deps should be installed using requirements.txt file instead of simply installing the latest version (which isn't actually yet supported by the custom docs theme). We can ensure we clarify that instead, and simply elide the three (!) manual lists of dependencies, which are bound to drift out of sync with the requirements.txt.

2/ "You can also specify the location of sphinx-build with the SPHINXBUILD make variable" => this also makes me think sphinx-build is okay to be anywhere, but it is not.

This is a highly niche detail that even advanced users are unlikely to need (assuming it even works), so it can simply be eliminated here and left to the README to document—it certainly doesn't belong in the lede, of all places.