[Doc-SIG] Python docs in reST

Michael Foord mike at pcblokes.com
Wed May 18 09:28:04 CEST 2005


Ian Bicking wrote:

> [snip..]
>
>Personally I've never seen a three-pane autogenerated reference document 
>that I've liked.  But eh... I think I'm just expecting too much from one 
>tool.  I guess one problem is that Python doesn't have good a formal 
>notion of "public" vs "private", so a lot of cruft and implementation 
>will show up in a autogenerated document.
>  
>
Yup. One of the biggest problems I've had with autogenerating 
documentation is that there is usually no way to mark a method/function 
as private other than the double underscore name mangling (which isn't 
usually what you want to do).

There is also, usually, no way of adding documentation to constants 
within a module - other than in the module docstring itself.

I've often thought about implementing something myself to overcome these 
problems. My favourite solution would allow some documentation in 
comments as well.

Some of the difficulties that people experience with epydoc are because 
it imports modules to extract docstrings. The advantage this has is that 
it allows it to link classes to their superclasses by inspecting them. 
Simple parsing would eliminate some problems that people experience - 
but make it much harder to obtain class/superclass information.

I've never really looked at/used pydoc - I wonder how hard it would be 
to add a useful synergy with reST ?? It's certainly an area I'd be 
willing to put some work into.

Best Regards,


Fuzzy
http://www.voidspace.org.uk/python/

>But, I'm feeling a need to autogenerate some documentation for Paste_, 
>so I have to figure out some of this myself.  Right now I'm thinking of 
>building a little scraper that uses metadata specifically applicable to 
>the project -- for instance, I want to keep indexes and make nice 
>documentation of all the configuration values, and all the WSGI 
>environment keys different components use.  Obviously this kind of 
>metadata is quite structured and (in the specific sense) not widely 
>applicable.
>
>If PEAK_ was more like a tool and less like a worldview, I'd probably 
>try to see what Phillip has done there, as I know he worked (or at least 
>thought) about a kind of customizable system like this.  But I'm afraid 
>it's too much for me to get my head around right now :( -- anyway, I 
>can't find it in CVS there, so maybe it never got to the point of code.
>
>.. _docutils: http://docutils.sourceforge.net/
>.. _ReST: http://docutils.sourceforge.net/rst.html
>.. _pydoc: http://python.org/doc/current/lib/module-pydoc.html
>.. _Epydoc: http://epydoc.sourceforge.net/
>.. _Paste: http://pythonpaste.org
>.. _PEAK: http://peak.telecommunity.com/
>
>  
>



More information about the Doc-SIG mailing list