Python source code documentation?

[Mark Hammond]

Sam Schulenburg wrote in message <7kdv0l$n0g$1 at nnrp1.deja.com>...
>I have been using a freeware product called Autoduck to document my
>Python source code.

Cool!  I use AutoDuck to document all my Python extension C++ code.  All the
helpfiles in the Win32 extensions are generated using autoduck.

As another poster pointed out, you should look at pythondoc/gendoc.  Sorry
in advance for the length of this, but I am in exactly the same predicament
as you, and have been thinking for a number of years how to resolve this.
Im really pleased to finally find someone else with this problem, and really
hope we can solve it in a reasonable way.

However, depending on how far you have gone with AutoDuck, pythondoc/gendoc
isnt solving the exact same problem.  Well, they all attempt to solve the
same problem, but have different strengths.

IMO, AutoDuck generates far superior reference documentation.  Pythondoc's
big strength is the integration with Python.  Using docstrings is an obvious
advantage, and much of what you need to explicitely mark-up using autoduck,
pythondoc already knows.

AutoDuck has 3 strengths over pythondoc that I am having trouble
reconciling:
* pythondoc really doesnt support natural links to objects.  Autoduck can
say "see method <om Foo.Bar>" or "@xref object|method" to generate inline
links or a cross-references section.  Has been some discussion how to expand
Pythondoc to support this, but a) it hasnt been done and b) it still is not
as natural as autoduck.

* Autoduck pulls-apart and re-assembles the output.  For example, one method
you may define entries in the following order: return description, params,
notes and cross-references.  A different method may define them in a
completely different order (as the best place to add the documentation is
right next to the appropriate code.  Autoduck will still always produce a
reference guide formatted as you choose - eg, always "params, return desc,
comments, cross-referneces".

* It can be used to document C extensions damn well.

Some of these problems boil down to an underlying philosophy of pythondoc -
attempting to use raw, unmarked docstrings to produce the doc.  Pythondoc
really doesnt want to introduce ugly mark-ups in the docstring, as this
tends to make the docstring hard to use in native form - it really _must_ be
read via the document generation tool.  This would be a serious bummer given
Python's introspective nature, and that IDE's may use this info on the fly.
(otoh, autoduck info doesnt exist at runtime at all!)

Sooooo.  I have come to the conclusion that we need a _new_ tool -
PythonDuck.  It should work with Pythondoc, and be capable of enhancing its
output.  A new release of pythondoc uses XML I believe, so PythonDuck could
be a tool that can enhance the documentation generated by pythondoc.
Alternatively we just graft it in, and beat up Daniel until he agrees :-)

This tool could possibly still work from comments, or maybe from the
tail-end of the doc strings (thereby stripped from the documentation, and
not messing the raw docstring too much).  #@ comments could be considered
"directives" for the generated output.  Eg, "#@ xref SomeOtherFunction" will
create a cross-references section.  A comment such as "#@ paramtype
param_name <o SomeType>" would direct that the param called "param_name"
should be documented as being of type "SomeType" and a cross-reference to
the SomeType definition be added.  The tool should resolve all links at the
end, and report bad links.

I know I am not making my point that well, and unfortunately dont have time
to fix this.  But in summary, Pythondoc exists and is very cool, but doesnt
quite cover what AutoDuck can do (and vise-versa, but that isnt the point
now).  I believe a real need exists for the functionality AutoDuck provides,
and further I need it personally!  So we should try and make this happen...

Mark.