[Doc-SIG] Approaches to structuring module documentation

[Paul Prescod]

"Fred L. Drake, Jr." wrote:
> 
>   I'm not convinced.  If what we end up with is little different from
> what we have, I don't see why we need to convert at all.  

I think we want to be able to slice and dice the documentation with
tools like Zope, 4XSLT, xt.exe and Internet Explorer 5.0

>   So I've been playing with a little tool to create documentation from
> a Python parse tree.  

Would the right compromise be to have very specific documentation inside
the Python and relatively generic documentation outside?

The reason I proposed that we might need a grammar change is because
when I last thought about this I couldn't figure out how to document
parameters without repeating their names. Maybe that's not such a
significant thing though. Also, I was trying to avoid using comments
because I wanted the same documentation to be available as docstrings.

-- 
 Paul Prescod  - ISOGEN Consulting Engineer speaking for himself
It's such a 
Bore
Being always
Poor
LANGSTON HUGHES
http://www.northshore.net/homepages/hope/engHughes.html