[Python-Dev] Sphinx version for Python 2.x docs

[Georg Brandl]

Am 23.08.2011 01:09, schrieb Sandro Tosi:
> Hi all,
> 
>> Any chance the version of sphinx used to generate the docs on
>> docs.python.org could be updated?
> 
> I'd like to discuss this aspect, in particular for the implication it
> has on http://bugs.python.org/issue12409 .
> 
> Personally, I do think it has a value to have the same set of tools to
> build the Python documentation of the currently active branches.
> Currently, only 2.7 is different, since it still fetches (from
> svn.python.org... can we fix this too? suggestions welcome!) sphinx
> 0.6.7 while 3.2/3.3 uses 1.0.7.
> 
> If you're worried about the time needed to convert the actual 2.7 doc
> to new sphinx format and all the related changes, I volunteer to do
> the job (and/or collaborate with whom is already on it), but what I
> want to understand if it's an acceptable change.
> 
> I see sphinx more as of an internal, building tool, so freezing it
> it's like saying "don't upgrade gcc" or so. Now the delta is just the
> C functions definitions and some py-specific roles, but during the
> years it will increase. Keeping it small, simplifying the forward-port
> of doc patches (not needing to have 2 version between 2.7 and 3.x
> f.e.) and having a common set of tools for doc building is worth IMHO.
> 
> What do you think about it? and yes Georg, I'd like to hear your opinion too :)

One of the main reasons for keeping Sphinx compatibility to 0.6.x was to
enable distributions (like Debian) to build the docs for the Python they ship
with the version of Sphinx that they ship.

This should now be fine with 1.0.x, so since you are ready to do the work of
converting the 2.7 Doc sources, it will be accepted.  The argument of easier
backports is a very good one.

The issue of using svn to download the tools is orthogonal; for this I would
agree to just packaging up a tarball or zipfile that is then downloaded using a
small Python script (should be properly cross-platform then).  Cloning the
original repositories is a) not useful, b) depends on availability of at least
two additional servers (remember docutils) and c) requires hg and svn.

Georg