Mailing List Archive

Sam Schulenburg wrote:
>
> I have been using a freeware product called Autoduck to document my
> Python source code.
>
> [...]
>
> I would prefer to have a Python based solution that would generate HTML
> files. Can anyone point me towards any information that may start me
> down this path, If a solution does not exist, then I may have to write
> my own Python parser to handle this.

Take a look at pythondoc or gendoc:

http://starship.python.net/crew/danilo/pystuff.html

Greetings,
--
Ovidiu Predescu <ovidiu@cup.hp.com>
http://www.geocities.com/SiliconValley/Monitor/7464/

Sam Schulenburg wrote in message <7kdv0l$n0g$1@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.

Mark Hammond wrote:
>
> Sam Schulenburg wrote in message <7kdv0l$n0g$1@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.
[...]
> 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.

Another package you may want to look at is Mark Peskin's Perceps:
http://friga.mer.utexas.edu/mark/perl/perceps/
The following site docs for a C++ library were done with it (frames and
all, but I didn't want to activate the Java class hierarchy browser):
http://www.equi4.com/metakit/info/docs/

Perceps was written in that other p-language, last time I checked.

'nother idea, since we have some many of these tools, and so many
languages (including SWIG, which also disects definitions), why not
define a "language -> XML" defs/docs extractor, plus a package which
turns that into docs, pdf's, help files, web sites (indexed), and such?

-- Jean-Claude

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.

Greg

Greg Ewing wrote in message <376D5BA2.70D845C4@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.