From fdrake at acm.org  Wed Aug  6 13:21:35 2003
From: fdrake at acm.org (Fred L. Drake, Jr.)
Date: Wed Aug  6 12:22:17 2003
Subject: [Doc-SIG] Old versions of the docs on python.org
Message-ID: <16177.11023.741887.520048@grendel.zope.com>


We've been working on cleaning up python.org lately.  There are a lot
of old versions of the Python documentation on the site; I'd like to
remove versions which predate 1.5.2 from the website (not from the FTP
archive, though).

Any objections?  Suggestions?


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

From garth at deadlybloodyserious.com  Fri Aug  8 12:06:47 2003
From: garth at deadlybloodyserious.com (Garth Kidd)
Date: Thu Aug  7 21:07:38 2003
Subject: [Doc-SIG] Old versions of the docs on python.org
In-Reply-To: <16177.11023.741887.520048@grendel.zope.com>
Message-ID: <000201c35d49$5b66ded0$3d00800a@gkiddxp2>

> We've been working on cleaning up python.org lately.  There 
> are a lot of old versions of the Python documentation on the 
> site; I'd like to remove versions which predate 1.5.2 from 
> the website (not from the FTP archive, though).
> 
> Any objections?  Suggestions?

I suggest keeping them on the site, but adding META tags suitable for
preventing search engines from indexing them. People will thus be funnelled
to the main documentation because that's where the search results will
point, but those specifically interested in the old stuff will be able to
read it without going to the hassle of downloading the full set with FTP. 

You'll need to have at least one indexable page link to the old docs by name
and version, though, so that a search for "Python 1.4 documentation" etc
will succeed. 

Regards,
Garth.


From aahz at pythoncraft.com  Thu Aug  7 22:57:07 2003
From: aahz at pythoncraft.com (Aahz)
Date: Thu Aug  7 21:57:25 2003
Subject: [Doc-SIG] Old versions of the docs on python.org
In-Reply-To: <000201c35d49$5b66ded0$3d00800a@gkiddxp2>
References: <16177.11023.741887.520048@grendel.zope.com>
	<000201c35d49$5b66ded0$3d00800a@gkiddxp2>
Message-ID: <20030808015707.GA25431@panix.com>

On Fri, Aug 08, 2003, Garth Kidd wrote:
> Fred Drake:
>>
>> We've been working on cleaning up python.org lately.  There 
>> are a lot of old versions of the Python documentation on the 
>> site; I'd like to remove versions which predate 1.5.2 from 
>> the website (not from the FTP archive, though).
>
> I suggest keeping them on the site, but adding META tags suitable for
> preventing search engines from indexing them. People will thus be
> funnelled to the main documentation because that's where the search
> results will point, but those specifically interested in the old stuff
> will be able to read it without going to the hassle of downloading the
> full set with FTP.

+1 -- provided anyone has the time to do it
-- 
Aahz (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/

This is Python.  We don't care much about theory, except where it intersects 
with useful practice.  --Aahz

From fdrake at acm.org  Tue Aug 12 12:38:28 2003
From: fdrake at acm.org (Fred L. Drake, Jr.)
Date: Tue Aug 12 11:39:22 2003
Subject: [Doc-SIG] Old versions of the docs on python.org
In-Reply-To: <000201c35d49$5b66ded0$3d00800a@gkiddxp2>
References: <16177.11023.741887.520048@grendel.zope.com>
	<000201c35d49$5b66ded0$3d00800a@gkiddxp2>
	<20030808015707.GA25431@panix.com>
Message-ID: <16185.2548.968283.755832@grendel.zope.com>


Garth Kidd writes:
 > I suggest keeping them on the site, but adding META tags suitable for
 > preventing search engines from indexing them. People will thus be funnelled
 > to the main documentation because that's where the search results will
 > point, but those specifically interested in the old stuff will be able to
 > read it without going to the hassle of downloading the full set with FTP. 

Excellent!  The implementation is a little different though; the old
versions are disallowed to web crawlers using robots.txt, and the
doc/versions.html has a "nofollow" <meta> tag.

 > You'll need to have at least one indexable page link to the old docs by name
 > and version, though, so that a search for "Python 1.4 documentation" etc
 > will succeed. 

doc/versions.html is indexable and provides just that sort of entry
point.

Aahz writes:
 > +1 -- provided anyone has the time to do it

I think this is completed now.  If I've missed anything in
implementing this, please let me know.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

From lars at ibp.de  Mon Aug 18 18:11:31 2003
From: lars at ibp.de (Lars Immisch)
Date: Mon Aug 18 11:11:16 2003
Subject: [Doc-SIG] Referencing specific function/class inside howto
Message-ID: <3F40ECA3.9000108@ibp.de>

Dear all,

I am using the existing Python documentation framework to write a howto 
for some internal software.

I want to reference specific functions and/or classes from other 
functions/classes, not just sections. To invent an example that 
hopefully illustrates my point:

I want to do something along the lines of:

\begin{funcdesc}{foo}{arg}
\code{arg} must be a class of type \code{Bar}. See \ref{Bar} for a 
description.
\end{funcdesc}

\begin{classdesc}{Bar}{baz}
Class \code{Bar} is froody and is constructed from a sprocket.
\end{classdesc}

I can't see how to do this and can't even find an example in the 
existing Python documentation source.

Any hints are appreciated.

Please Cc: me in your replies, since I am not subscribed to the doc-sig yet.

- Lars Immisch


From fdrake at acm.org  Mon Aug 18 12:18:00 2003
From: fdrake at acm.org (Fred L. Drake, Jr.)
Date: Mon Aug 18 11:18:37 2003
Subject: [Doc-SIG] Referencing specific function/class inside howto
In-Reply-To: <3F40ECA3.9000108@ibp.de>
References: <3F40ECA3.9000108@ibp.de>
Message-ID: <16192.60968.773702.797700@grendel.zope.com>


Lars Immisch writes:
 > I am using the existing Python documentation framework to write a howto 
 > for some internal software.

Cool!

 > I want to reference specific functions and/or classes from other 
 > functions/classes, not just sections. To invent an example that 
 > hopefully illustrates my point:

I'm afraid that's not currently supported, though I've started
thinking about ways to introduce that.  I haven't had a lot of time to
spend on it yet.


  -Fred

-- 
Fred L. Drake, Jr.  <fdrake at acm.org>
PythonLabs at Zope Corporation

From castor at snafu.de  Mon Aug 18 20:54:22 2003
From: castor at snafu.de (Wolfgang Lipp)
Date: Mon Aug 18 13:54:23 2003
Subject: [Doc-SIG] Referencing specific function/class inside howto
Message-ID: <E19ooCv-0000FL-00@smart.eusc.inter.net>


i am not sure i understood the question completely, but epydoc+docutils
is able to reference functions in modules included in one documentation 
build. you would simple write `mymodule.xy` and there you are.

i am using the docutils together with epydoc, and find i can recommend
the combo as the best source documentation solution available for 
python. i did patch a few lines in epydoc and wrote an additional module
to do file globbing, though, but in most cases it should work with simply
setting up epydoc and docutils and then issue sth along the lines of 

pathto\epydoc.py --target doc --css blue --docformat restructuredtext *.py

from the directory where your sources live. of course, this makes only sense
if your sources are python files, for otherwise epydoc couldn't handle them. 
unfortunately, since file globbing didn't seem to work with the last release
of epydoc, you may have to replace the ``*.py`` with a list of all your 
files. 

i think it would make sense to urge the developer of epydoc to get some 
really minor quirks out of the current release, write one or two short 
scripts and perhaps even make a docutils/epydoc bundle so developers and
laymen alike can install and run it with even less hassle than today. 

yours, 

_wolf


ps. for those interested, http://python.org/pypi?:action=display&name=tracy&version=0.1
provides docs & sources as an example application of the epydoc+docutils. 



>
>Subject: Re: [Doc-SIG] Referencing specific function/class inside howto
>   From: "Fred L. Drake, Jr." <fdrake@acm.org>
>   Date: Mon, 18 Aug 2003 11:18:00 -0400
>     To: Lars Immisch <lars@ibp.de>
>     Cc: doc-sig@python.org
>
>
>Lars Immisch writes:
> > I am using the existing Python documentation framework to write a howto 
> > for some internal software.
>
>Cool!
>
> > I want to reference specific functions and/or classes from other 
> > functions/classes, not just sections. To invent an example that 
> > hopefully illustrates my point:
>
>I'm afraid that's not currently supported, though I've started
>thinking about ways to introduce that.  I haven't had a lot of time to
>spend on it yet.
>
>
>  -Fred
>
>-- 
>Fred L. Drake, Jr.  <fdrake at acm.org>
>PythonLabs at Zope Corporation
>
>_______________________________________________
>Doc-SIG maillist  -  Doc-SIG@python.org
>http://mail.python.org/mailman/listinfo/doc-sig

From goodger at python.org  Wed Aug 27 19:11:05 2003
From: goodger at python.org (David Goodger)
Date: Wed Aug 27 18:12:32 2003
Subject: [Doc-SIG] Docutils config file reorganization
Message-ID: <3F4D2C79.3050009@python.org>

Just checked in; "[options]" is dead (well, hanging on by a thread),
long live "[general]", "[html4css1 writer]", etc. etc.  Docs here:
<http://docutils.sf.net/docs/config.html>.  Please take it out for a
good spin, and let me know if there are any problems.

To convert existing config files, the easiest way is to change
"[options]" to "[general]".  Most settings haven't changed.  The only
ones to watch out for are these:

     pep_stylesheet      -->  [pep_html writer] stylesheet
     pep_stylesheet_path -->  [pep_html writer] stylesheet_path
     pep_template        -->  [pep_html writer] template

The old-style config files will still work, but a deprecation warning
is issued.

-- 
David Goodger    http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)