Mailing List Archive: Python: Bugs

[issue15605] Explain sphinx documentation building in devguide

Index | Next | Previous | View Threaded

report at bugs

Aug 9, 2012, 10:36 AM

Post #1 of 5 (48 views)
Permalink

[issue15605] Explain sphinx documentation building in devguide

New submission from Daniel Ellis:

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:

python tools/sphinx-build.py -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 sphinx-build.py 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.

----------
components: Devguide
messages: 167800
nosy: Daniel.Ellis, eric.araujo, ezio.melotti, ncoghlan
priority: normal
severity: normal
status: open
title: Explain sphinx documentation building in devguide

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

report at bugs

Aug 9, 2012, 10:42 AM

Post #2 of 5 (47 views)
Permalink

[issue15605] Explain sphinx documentation building in devguide [In reply to]

R. David Murray added the comment:

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.

----------
nosy: +r.david.murray

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

report at bugs

Aug 9, 2012, 11:29 AM

Post #3 of 5 (48 views)
Permalink

[issue15605] Explain sphinx documentation building in devguide [In reply to]

Daniel Ellis added the comment:

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?

----------
keywords: +patch
Added file: http://bugs.python.org/file26745/devguide_sphinx_fix.patch

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

report at bugs

Aug 9, 2012, 11:56 AM

Post #4 of 5 (47 views)
Permalink

[issue15605] Explain sphinx documentation building in devguide [In reply to]

Chris Jerdonek added the comment:

+If you are building the developer's guide, or for some other reason can not use
+the `tools/sphinx-build.py` file, you can also run the following command from
+the directory containing `conf.py` ::
+
+ 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:

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.

----------
nosy: +cjerdonek

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

report at bugs

Aug 12, 2012, 5:53 AM

Post #5 of 5 (42 views)
Permalink

[issue15605] Explain sphinx documentation building in devguide [In reply to]

Changes by Tshepang Lekhonkhobe <tshepang [at] gmail>:

----------
nosy: +tshepang

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads