[docs] Which version of sphinx?

[Sandro Tosi]

On Sat, Jun 11, 2011 at 01:27, Tshepang Lekhonkhobe <tshepang at gmail.com> wrote:
> On Fri, 2011-06-10 at 20:40 +0000, Sandro Tosi wrote:
>> Hello Tshepang,
>>
>> On Thu, Jun 2, 2011 at 23:56, Tshepang Lekhonkhobe <tshepang at gmail.com> wrote:
>> > Hi,
>> >
>> > Is there any reason Sphinx version was specified here:
>> > http://docs.python.org/dev/documenting/building.html?
>>
>> I don't have that clear your question. Are you asking why the version
>> is explict in this command:
>>
>> svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx
>>
>> or in some other place? can you please be a bit more specific (either
>> in what you think is wrong and how you'd fix it)?
>
> Sorry for not being too clear. I meant, why is that specific version
> required? Why doesn't the link just point to trunk (or tip, in Mercurial
> speak)?

I can think mainly two reason:

- stability: if everyone is building the docs from sphinx tip (and all
other third-party tool) you'll get a mess where for some people the
change works and for others doesn't. Having "written in stone" what's
the version to use, avoid this ambiguity.
- that's because it's what Makefile does: if you look at Doc/Makefile
(of the cpython default branch checkout) you'll see the script is
actually checking out the code from svn.python.org - for strange that
it is, it works.

> I asked because I was looking at the doc, wanting to improve it.
> I imagined it could stem from the fear that later versions could break
> the doc build.

Indeed, just use the tool Python ship: the makefile will DTRT, just follow it :)

If you need help, or guidance, about improving the doc, you can ask
here, on python-dev or refer to the devguide:
http://docs.python.org/devguide/docquality.html

Regards,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi