Python source code documentation?

[Mark Hammond]

Greg Ewing wrote in message <376D5BA2.70D845C4 at compaq.com>...
>Mark Hammond wrote:
>>
>> Pythondoc
>> really doesnt want to introduce ugly mark-ups in the docstring
>
>What about non-ugly markups? Surely it's possible to
>design a form of markup which doesn't look ugly.

Well, "ugly" is in the eye of the beholder :-)

The issue is a phrase such as:
"This method is very similar to <om OtherClass.ItsMethod>, but different"

Clearly, when reading the docstring as a docstring in the source-code, this
would qualify as ugly.  It distracts from the user reading the text.
Similarly, <B> </B> is also ugly, hence Pythondoc/structured text can
convert *bold* into bold (for example).

However, as far as marked-up text goes, I really dont consider my example
ugly.  Once you know that "om==object method", it really isnt that bad.

I suppose what I was trying to say was "Pythondoc doesnt want to introduce
mark-ups in the docstring as they are ugly" :-)

Indeed, Pythondoes goes some way to move all links to the bottom of the
docstring.  I cant remember the exact format, but the text and the just
target are kept seperate from each other.  The analogy would be that in my
world, I would consider:
Please see <jump The Python homepage:www.python.org>

quite acceptable, and indeed quite an improvement (wrt maintenance) if you
consider the generated documentation the "primary documentation" - ie, the
format people will most often use to read the docstrings.

In fact, I believe this is the biggest difference between the pythondoc
focus and the autoduck type focus.  Pythondoc strives to keep completely
readable docstrings and generate good documentation.  Autoduck type
formatting is happy to sacrifice some of the docstring readability in order
to create better documentation.

[Important to recall autoduck started as autodoc, which can parse C code and
marked up comments.  This is quite a different environment to Python
docstrings available at runtime.]

Mark.