This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Explain sphinx documentation building in devguide
Type: Stage: resolved
Components: Devguide Versions:
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: Daniel.Ellis, chris.jerdonek, eric.araujo, ezio.melotti, georg.brandl, ncoghlan, python-dev, r.david.murray, terry.reedy, tshepang, zach.ware
Priority: normal Keywords: patch

Created on 2012-08-09 17:36 by Daniel.Ellis, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit
devguide_sphinx_fix.patch Daniel.Ellis, 2012-08-09 18:29
Messages (12)
msg167800 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-09 17:36
At the bottom of this page:

There is a command explaining how to build the documentation without using make:

    python tools/ -b<builder> . build/<outputdirectory>

It is unclear as to which directory the "tools" is referring to.  In the "Tools" directory of the main branch, there is no file.

On my system, I was able to do the build using sphinx-build as a bare command:

    sphinx-build -b<builder> . build/<outputdirectory>

I am not sure if this is system specific, but for someone building the documentation for the first time (as I was), this could be confusing.  Perhaps someone could explain whether the command that is currently written is obsolete or just differs by system.
msg167802 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-08-09 17:42
It refers to the 'tools' subdirectory in the Doc directory, but that doesn't exist unless you've built the docs with 'make' before, or done a 'make checkout'.

Presumably you have sphinx installed on your system separately, and that's why you were able to run the command without having done the checkout.  This will most work fine I think, though occasionally differences between the system sphinx version and the version the checkout is using will cause issues.

Yes, the devguide should be updated to explain how one gets a 'tools' directory.
msg167807 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-09 18:29
That makes sense.  I've added a brief explanation noting that the user should be in the "Docs" directory to run the command.  When trying to update the dev guide, I noticed that this same "tools" directory does not exist in the repo, so I also added instructions for using the command as mentioned above.  For concision's sake, would it be good to remove the reference to the "tools/" file altogether?
msg167816 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-09 18:56
+If you are building the developer's guide, or for some other reason can not use
+the `tools/` file, you can also run the following command from
+the directory containing `` ::
+   sphinx-build -b<builder> . build/<outputdirectory>

Note that the build instructions for the Developer's Guide live at a separate location at the bottom of this page:

Also, IIRC the build directory for the Developer's Guide is "_build" rather than "build" as it is for the main Python documentation.

Lastly, a couple nits: "Developer's Guide" should be capitalized and "can not" should be one word.
msg183634 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-07 07:05
I initially had a bit of the same confusion as Daniel, and hence agree on clarifying.

I have more comments on 7.6. Building the documentation.

1. "You need to have Python 2.4 or higher installed."

Until 3.x docs can be built with 3.x, (and I just verified that this is 'not yet') change '2.4 or higher' to '2.4 to 2.7'.

1A. "To build the documentation, follow the instructions from one of the sections below."

Perhaps we should add "These instructions assume that <repository>/Doc/ is the current directory." Then we would not have to repeat in multiple places.

2. "7.6.1. Using make On Unix, ..."

It turns out that there is an almost easy-to-use make.bat that *almost* works the same. So it should be documented, but, unfortunately, we cannot just say "On Unix or Windows ...".

One problem is this line:
if "%PYTHON%" EQU "" set PYTHON=..\pcbuild\python
Since we elsewhere say to build python_d.exe rather than python.exe for development, that line needs '_d' added. But even with that correction, making docs will still fail for 3.x. So we need a new paragraph that says something like
On Windows, with svn available, download the needed modules with
...\Doc> make checkout            [in code box]
As with unix, update with "make update". Make the html docs with [in code box]
...\Doc> set PYTHON=<path to 2.x executable>
...\Doc> make html
The list of other possible targets is almost the same, except that “coverage” and “pydoc-topics” are not available, which "suspicious" warns about suspicious constructs that are not errors.
Perhaps "suspicious" is available on *nix, just not documented. Could someone check?

The need to set PYTHON each session is a nuisance. I made another batch file with the correct setting for my system. But that will keep showing up as a file to be added. I will try to write a master dmake.bat file that sits outside of the repository directories. Once working, it might be suitable as a template.

3. "Then, make an output directory, e.g. under `build/`"

This is awkward, both before and after the proposed patch and is overly stingly with words. I suggest:

"While in the Doc directory, make a master output directory `build/` that will contain subdirectories for each target, such as `build/html/`.  Then run ..."

4. "the directory containing `` "

Why the euphimism for Doc/? Is it ever anything else.
msg183694 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-03-07 18:52
> change '2.4 or higher' to '2.4 to 2.7'.

"Python 2" should be enough.

> Perhaps we should add "These instructions assume that <repository>/Doc/
> is the current directory." Then we would not have to repeat in multiple 
> places.

There was a somewhat related discussion about this in #16814.

> But even with that correction, making docs will still fail for 3.x.

Maybe we should just updated Sphinx :)  See #10224.

> Perhaps "suspicious" is available on *nix, just not documented.
> Could someone check?

It is.  See also #15759.

> "Then, make an output directory, e.g. under `build/`"

On Linux sphinx-build/"make html" takes care of this already.  Is this not the case on Windows?  If not maybe the make.bat should be updated.
msg183707 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-07 22:16
>"Python 2" should be enough.
I thought about that. Agreed.

"make -C Doc xxx" will not work with make.bat. Perhaps "7.6.1. Using make" should be expanded to "7.6.1 Using make on unix" and "7.6.2 Using make on Windows" added. Then the directory assumption could be put in the latter. But see below.

I super agree that all the doc building modules should work on 3.x, or at least 3.3+, so a freshly built 3.x can build its own docs. But until they do, we need to document what works now. I added a note on #10224.

OK, add 'suspicious' to the unix list and the Windows difference is reduced. (By the way, suspicious.cvs for 3.4 has 22 lines now.)

I presume that unix make *also* has a 'checkout' target, but it is just not mentioned because the other targets list it as a dependency so it gets called automatically.

If so, the unix/windows difference would be reduced further if checkout were listed in the master list, with a note that explicit 'make checkout' is only needed on windows. I think that should be the first target listed, with update following. The last two targets that do not work on Windows could have 'Unix only'. Then a separate Windows section might not be needed -- though a paragraph about setting PYTHON would still be needed until it is not needed.

Yes, make.bat add /build, etc, as needed.
if not exist build mkdir build
if not exist build\%1 mkdir build\%1
if not exist build\doctrees mkdir build\doctrees
(It is really a nice .bat file.)

The line about making /build oneself is in the section about *not* using make. Perhaps this section was written before make.bat? Does Mac lack make? If not, this section might be recast as explaining what make does.
msg183840 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2013-03-09 19:26
In issue17386, I have offered a patch to Doc/make.bat which makes using make.bat on Windows very, very nearly the same as using make on UNIX.  With such a patch applied, it would be trivial to rewrite section 7.6.1 with instructions that apply equally well to both platforms.

> "make -C Doc xxx" will not work with make.bat.

In issue16895, there is a make.bat file intended for the root of the Python repository, which, if there is any interest, could be fairly easily expanded to support a "make -C Doc xxx" command.  In fact, the version posted includes a "doc" target, which does essentially the same thing as "make -C Doc xxx".
msg213054 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-10 17:58
Note that 3.4 finally removes getting Sphinx from a subversion repository, so the installation instructions will need a version-specific part for that.
msg213055 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-10 18:19
New changeset f32569ddc2db by Georg Brandl in branch 'default':
Closes #15605: update and refurbish doc building section of the devguide.
msg213056 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-03-10 18:20
Thanks for your patience. I believe I have addressed all issues raised.
msg213060 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-10 18:30
Updated text is clear and comprehensive, thanks!

Another edit could be done after the packaging docs is revamped to add links to the pyvenv and pip sections of the doc, to avoid users reading “install Sphinx and its deps” and not knowing how to do that.
Date User Action Args
2022-04-11 14:57:34adminsetgithub: 59810
2014-03-10 18:30:35eric.araujosetmessages: + msg213060
2014-03-10 18:20:22georg.brandlsetnosy: + georg.brandl
messages: + msg213056
2014-03-10 18:19:49python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg213055

resolution: fixed
stage: resolved
2014-03-10 17:58:08eric.araujosetmessages: + msg213054
2013-03-09 19:26:05zach.waresetnosy: + zach.ware
messages: + msg183840
2013-03-07 22:16:18terry.reedysetmessages: + msg183707
2013-03-07 18:52:32ezio.melottisetmessages: + msg183694
2013-03-07 07:05:20terry.reedysetnosy: + terry.reedy
messages: + msg183634
2012-08-12 12:53:43tshepangsetnosy: + tshepang
2012-08-09 18:56:19chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg167816
2012-08-09 18:29:02Daniel.Ellissetfiles: + devguide_sphinx_fix.patch
keywords: + patch
messages: + msg167807
2012-08-09 17:42:44r.david.murraysetnosy: + r.david.murray
messages: + msg167802
2012-08-09 17:36:08Daniel.Elliscreate