List which receives bug reports on Python

Daniel Ellis | 9 Aug 2012 19:36

[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

_______________________________________

(Continue reading)

headers

R. David Murray | 9 Aug 2012 19:42

[issue15605] Explain sphinx documentation building in devguide


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.python.org>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/python-python-bugs-list%40m.gmane.org

headers

Daniel Ellis | 9 Aug 2012 20:29

[issue15605] Explain sphinx documentation building in devguide


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.python.org>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/python-python-bugs-list%40m.gmane.org

headers

Chris Jerdonek | 9 Aug 2012 20:56

[issue15605] Explain sphinx documentation building in devguide


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.python.org>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/python-python-bugs-list%40m.gmane.org

(Continue reading)

headers

Tshepang Lekhonkhobe | 12 Aug 2012 14:53

[issue15605] Explain sphinx documentation building in devguide


Changes by Tshepang Lekhonkhobe <tshepang <at> gmail.com>:

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

_______________________________________
Python tracker <report <at> bugs.python.org>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/python-python-bugs-list%40m.gmane.org

headers

Terry J. Reedy | 7 Mar 2013 08:05

[issue15605] Explain sphinx documentation building in devguide


Terry J. Reedy added the comment:

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]

(Continue reading)

headers

Ezio Melotti | 7 Mar 2013 19:52

[issue15605] Explain sphinx documentation building in devguide


Ezio Melotti added the comment:

> 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.

----------

_______________________________________

(Continue reading)

headers

Terry J. Reedy | 7 Mar 2013 23:16

[issue15605] Explain sphinx documentation building in devguide

Terry J. Reedy added the comment:

>"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.)

(Continue reading)

headers

Zachary Ware | 9 Mar 2013 20:26

[issue15605] Explain sphinx documentation building in devguide


Zachary Ware added the comment:

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".

----------
nosy: +zach.ware

_______________________________________
Python tracker <report <at> bugs.python.org>
<http://bugs.python.org/issue15605>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/python-python-bugs-list%40m.gmane.org