Repository navigation
Explain sphinx documentation building in devguide #59810
Description
| BPO | 15605 |
|---|---|
| Nosy | @birkenfeld, @terryjreedy, @ncoghlan, @ezio-melotti, @merwok, @bitdancer, @cjerdonek, @zware |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = <Date 2014-03-10.18:19:49.683>
created_at = <Date 2012-08-09.17:36:08.627>
labels = ['docs']
title = 'Explain sphinx documentation building in devguide'
updated_at = <Date 2014-03-10.18:30:35.453>
user = 'https://bugs.python.org/DanielEllis'bugs.python.org fields:
activity = <Date 2014-03-10.18:30:35.453>
actor = 'eric.araujo'
assignee = 'none'
closed = True
closed_date = <Date 2014-03-10.18:19:49.683>
closer = 'python-dev'
components = ['Devguide']
creation = <Date 2012-08-09.17:36:08.627>
creator = 'Daniel.Ellis'
dependencies = []
files = ['26745']
hgrepos = []
issue_num = 15605
keywords = ['patch']
message_count = 12.0
messages = ['167800', '167802', '167807', '167816', '183634', '183694', '183707', '183840', '213054', '213055', '213056', '213060']
nosy_count = 11.0
nosy_names = ['georg.brandl', 'terry.reedy', 'ncoghlan', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'chris.jerdonek', 'tshepang', 'python-dev', 'zach.ware', 'Daniel.Ellis']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue15605'
versions = []
Activity
DanielEllis commentedon Aug 9, 2012
At the bottom of this page: http://docs.python.org/devguide/documenting.html
There is a command explaining how to build the documentation without using make:
It is unclear as to which directory the "tools" is referring to. In the "Tools" directory of the main branch, there is no sphinx-build.py file.
On my system, I was able to do the build using sphinx-build as a bare command:
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.
bitdancer commentedon Aug 9, 2012
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.
DanielEllis commentedon Aug 9, 2012
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/sphinx-build.py" file altogether?
cjerdonek commentedon Aug 9, 2012
+If you are building the developer's guide, or for some other reason can not use
+the
tools/sphinx-build.pyfile, you can also run the following command from+the directory containing
conf.py::+
Note that the build instructions for the Developer's Guide live at a separate location at the bottom of this page:
http://docs.python.org/devguide/docquality.html#helping-with-the-developer-s-guide
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.
terryjreedy commentedon Mar 7, 2013
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.
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.
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.
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 asbuild/html/. Then run ..."conf.py"Why the euphimism for Doc/? Is it ever anything else.
ezio-melotti commentedon Mar 7, 2013
"Python 2" should be enough.
There was a somewhat related discussion about this in bpo-16814.
Maybe we should just updated Sphinx :) See bpo-10224.
It is. See also bpo-15759.
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.
terryjreedy commentedon Mar 7, 2013
"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 bpo-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.
zware commentedon Mar 9, 2013
In bpo-17386, 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.
In bpo-16895, 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".
merwok commentedon Mar 10, 2014
Note that 3.4 finally removes getting Sphinx from a subversion repository, so the installation instructions will need a version-specific part for that.
python-dev commentedon Mar 10, 2014
New changeset f32569ddc2db by Georg Brandl in branch 'default':
Closes bpo-15605: update and refurbish doc building section of the devguide.
http://hg.python.org/devguide/rev/f32569ddc2db
birkenfeld commentedon Mar 10, 2014
Thanks for your patience. I believe I have addressed all issues raised.
merwok commentedon Mar 10, 2014
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.