[Python-Dev] Python documentation

[Georg Brandl]

Barry Warsaw schrieb:
> On Sep 21, 2008, at 6:03 AM, Georg Brandl wrote:
> 
>> Barry Warsaw schrieb:
>>> Martin points out that in the past, as part of the release process,
>>> we've built separate downloadable documentation.
>>>
>>> Do we still want to do that for Python 2.6 and 3.0, and if so, how do
>>> we go about doing that?  I have this feeling that building the
>>> documentation is much different now than in the past, and I don't
>>> really have a good feel for how it's done now.
>>>
>>> If you think we should release separate downloadable documentation  
>>> and
>>> can help integrate that into the release project, you just might be a
>>> Documentation Expert <wink>.  Please let me know if you can help.
> 
>> There is almost everything ready for doing this. There is a "download"
>> page in the HTML docs (that at the moment contains nothing).
> 
>> If you tell me where the downloadable files will be on python.org, I  
>> can
>> add them to the "download" page and you only need to build the docs  
>> and
>> put them in that location. I've just added a "dist" target to the Doc/
>> Makefile, so a "make dist" should place all needed files in the Doc/ 
>> dist
>> directory, from where you can copy them to the desired location.
> 
> Benjamin has hacked on the release.py script to build and sign the  
> documentation.  I haven't tried it yet but it looks like it does a  
> 'make html' and exports that.
> 
> Given the above, we should change that to 'make dist' and update the  
> PEP to describe scp'ing them to dinsdale:/ftp/python/doc/X.Y using the  
> templates on this page: http://docs.python.org/download.html

I've now completed the download page for the new docs. The file names it
expects are currently

http://docs.python.org/ftp/python/doc/$version/python-docs-$format.$ext

which is what "make dist" generates.  If you want to have the version in
the filename as well, use "make dist DISTVERSION=2.6" and I'll adapt the
download page accordingly.

> I notice that for 2.5, we zip'd and tar-bz2'd them.  Do we want to  
> also support tgz?  We'll have to hack the release script to build the  
> doc zips.  I'll try to test drive this whole process soon.

As Fred says, bz2 should suffice. gzip offers no compression advantage
over zip either.

I've also dropped the PostScript download versions; I see no compelling
reason to use them instead of PDF.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.