Mailman 3 January 2005 - Doc-SIG

Re: [Doc-SIG] Good API doc generation in the Python world recently?
by Laura Creighton Jan. 28, 2005

Jan. 28, 2005

Sylvain, Ludovic Aubry and Adrien Di Mascio should be driving back to Logilab from the PyPy Sprint full of ideas. We need an AST for PyPy too, and we are of course interested in your PyLint work. Come hang out on #pypy at irc.freenode.net next week and we can discuss this more. Whatever we do for pypy it would be good if we could drop it into epydoc, make it part of CPython, and make everybody happy. Laura Creighton

1 0

Good API doc generation in the Python world recently?
by Christopher Armstrong Jan. 28, 2005

Jan. 28, 2005

I can't find any. HappyDoc is way, way out of date (it blows up on newer code, in certain situations, I think) and epydoc just has loads and loads of problems with its importing of code (at least with Twisted, and anything else using Zope Interfaces). Has anyone heard anything about better docstring-based API doc generation lately? I'm afraid I'm going to have to release Twisted 2.0 without API docs, but I'm considering improving HappyDoc after that. -- Twisted | Christopher Armstrong: International Man of Twistery Radix | -- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// | -- http://twistedmatrix.com |o O| | Founding Member, Hobart Hacking Society w----v----w-+ -- http://hackingsociety.org/chapters/hash

5 7

Hello and the threading module
by Alan Green Jan. 24, 2005

Jan. 24, 2005

Hi All, I've been working with Python for fun and profit (but mostly fun) for the last four years or so, and feel it's time for me to give something back. I've decided to see if I can help out with documentation a little. Looking through the documentation bugs on sourceforge, it seems that the threading module docs could do with a clean up - particularly to document edge cases, like what might happen if you were to pass None as a parameter. Would that be a good place to start? Meanwhile, I've already put up two patches. The first updates the "Working on Cygwin" section of Documenting Python. The second modifies a public API in order to make it simpler to document - perhaps a little too ambitiousfor somebody's second ever patch :). Alan -- Alan Green alan.green(a)cardboard.nu - http://cardboard.nu

1 0

reST ordered list syntax extension
by Andrew Harrington Jan. 15, 2005

Jan. 15, 2005

Desired feature change in restructured text (reST) ordered lists: Being able to add ordered list entries to the middle of a list without renumbering would be very useful. If I start with: 1. first 2. second a. sub a para b. sub b 3. third And I want to insert entry NEW after 1, I must renumber: 1. first 2. NEW 3. second a. sub a para b. sub b 4. third I suggest that the first entry in a list start with the actual format desired, but for later entries allow '#': 1. first #. second a. sub a para #. sub b #. third which would make the insertion easy: 1. first #. NEW #. second a. sub a para #. sub b #. third The parser already keeps track of what the next sequence identifier would be and issues errors if they are wrong. Why not just allow the # with the same punctuation after it and indentation before as in the first entry, and rather than declaring an error, substitute in the next in the sequence? An extension could allow fully labeled sublist entries If you wanted: 1. first 2. second 2.a. sub a para 2.b. sub b 3. third you could use in the extended reST: 1. first #. second #.a. sub a para #.#. sub b #. third The assumption is that if a first sub entry starts with one or more '#' and punctuation (the '#.' here), they are assumed to be repeats of the current outer levels, and there must be an explicit subsequence starter in addition (the 'a' here). I have written in that further sub entries must have the same prefix ('#.' here) as the first subentry. A more concise alternative would be to _assume the same prefix, and just allow #.#. sub b to be #. sub b I am not sure if the latter alternative should be indented to match the first instead of the second '#' in the alternate version above. The punctuation is important to be included explicitly if desired. If I gave input #a. sub a I would get out the more concise output 2a. sub a Comments? Thanks Andy Harrington

2 1