[Doc-SIG] epydoc 1.1 release

[M.-A. Lemburg]

Edward Loper wrote:
> M.-A. Lemburg wrote:
> 
>> Edward Loper wrote:
>>
>>> - Some advantages of pydoc are:
> 
>  >>     [...]
> 
>>
>> I like the output of epydoc a lot (except maybe for the dim
>> colors ;-). Wouldn't it be possible to add most of the above
>> in form of options to epydoc ?
> 
> 
> For some of these, they would be added (as defaults, not options) if I 
> had time to code them.  And there's plenty more on the epydoc todo list 
> (see the comment at the bottom of epydoc.py/__init__.py).
> 
> Others don't really go with epydoc's design philosophy.  In particular, 
> I doubt epydoc will ever automatically (implicitly) create intra-doc 
> links.  This can sometimes make mistakes, and puts links all over the 
> place.  I would rather have the user explicitly create links.  I'm also 
> unlikely to add support for processing python comments.  And I doubt 
> I'll add manpage-style and interpreter (pydoc.help) usage, because pydoc 
> already does such a good job at it, and is already part of the standard 
> library.

Hmm, that doesn't leave much ;-)

>> What I don't understand about epydoc is why it uses a syntax
>> that's almost JavaDoc-style, but not all the way ?
> 
> Actually, the only real similarity between epytext and javadoc comments 
> is that the @field's look roughly similar.

That's what I was looking at. Your @field defs look very similar,
but aren't compatible, e.g. was there a reason to add colons ? (this
is really what I'm interested in; not the HTML formatting used
in JavaScript)

>  E.g., note that you have to 
> use explicit <p>'s in javadoc to mark paragraph boundaries; and you have 
> to explicitly use <ul><li></ul> for lists, etc.
> 
> I find javadoc's markup conceptually ugly.  The idea of allowing 
> unrestricted html code in your docstring really bothers me.  And it 
> makes the docstrings very difficult to read when you're looking at the 
> source code.  That said, it might be good to add support for 
> javadoc-style docstrings, just because it would reduce the learning 
> curve for java programmers.  It wouldn't be that technically difficult 
> to do; javadoc docstrings are basically just raw html plus @field's. And 
> epydoc's docstring processing is pretty compartmentalized.  But I only 
> have limited time to spend on epydoc, and that's not a feature that I 
> feel very motivated to add.
> 
> If someone else wants to add it, I'd certainly accept a patch.  What 
> would probably be involved is:
> 
>   - Write epydoc/javadoc.html to parse javadoc-style comments.  It
>     would probably produce an xml document with a <javadoc> node
>     that contains a <rawhtml> node followed by a <fieldlist> node
>     similar to epytext's.  Of course, if you wanted to handle
>     javadoc's syntax for intradocumentation links, etc, you would
>     need to do a little more work.
>   - Patch ObjDoc.__parse_docstring in epydoc/objdoc.py to recognize
>     'javadoc' as a value for __docformat__.
>   - Patch HTML_Formatter._dom_to_html_helper in epydoc/html.py to
>     handle <rawhtml> elements.
>   - (Optionally) add all of the field's that javadoc implements that
>     epydoc does not (e.g., @since and @depreciated).
> 
> Then you could just use "--docformat javadoc" to set the default 
> docstring format to javadoc, or add "__docformat__='javadoc'" to each 
> module that uses javadoc-style docstrings.

Thanks for the instructions. I think I'll have a go once we're
sure that we need this.

-- 
Marc-Andre Lemburg
CEO eGenix.com Software GmbH
_______________________________________________________________________
eGenix.com -- Makers of the Python mx Extensions: mxDateTime,mxODBC,...
Python Consulting:                               http://www.egenix.com/
Python Software:                    http://www.egenix.com/files/python/