Mailman 3 August 2003 - Doc-SIG

Docutils config file reorganization
by David Goodger Aug. 27, 2003

Aug. 27, 2003

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)

1 0

Re: [Doc-SIG] Referencing specific function/class inside howto
by Wolfgang Lipp Aug. 18, 2003

Aug. 18, 2003

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(a)acm.org> > Date: Mon, 18 Aug 2003 11:18:00 -0400 > To: Lars Immisch <lars(a)ibp.de> > Cc: doc-sig(a)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(a)python.org >http://mail.python.org/mailman/listinfo/doc-sig

1 0

Referencing specific function/class inside howto
by Lars Immisch Aug. 18, 2003

Aug. 18, 2003

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

2 1

Old versions of the docs on python.org
by Fred L. Drake, Jr. Aug. 12, 2003

Aug. 12, 2003

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

3 3