[Doc-SIG] htmldoc.py and inspect.py

[Ka-Ping Yee]

At 15:09 30.05.00, Juergen Hermann wrote:
> I'm currently using pdoc.py, and I will definitely will give your script
> a look. What I would like VERY much would be a Python doc system that
> shares as much as possible with the JavaDoc/DOC++/Doxygen world,
> especially the "commands" to provide semantic markup (like \param spam).

On Tue, 30 May 2000, Walter [iso-8859-1] Dörwald wrote:
> I would prefer if the semantic markup would use XML. XML was designed
> to be used for stuff like that

This was a decision i made about the philosophy of the doc
generation script.  I chose to have it display the docstrings
exactly as they are in the code.  This makes the script small, 
predictable, and incapable of screwing up in any significant way. [1]

Also this avoids the entire issue of exactly what particular
structured-text formatting conventions you're going to use.
I do like structured text (indeed, WikiWiki is WwWonderful)
but you should see just how long discussions can go on and on
about how best to do this sort of thing.

Better to just get something done and working and out there
than continue debating, i think.

By the way, that's a very unusual middle name, Walter. :)



-- ?!ng

"To be human is to continually change.  Your desire to remain as you are
is what ultimately limits you."
    -- The Puppet Master, Ghost in the Shell

[1] The only "screw-up" i have noticed is in nturl2path.py and
reconvert.py, which mention "\b", "\f" etc. in their docstrings.
So for example the mention of "C:\foo" in nturl2path.py becomes
"C:", a form feed, and "oo".  I have submitted a little patch to
put an "r" in front of those docstrings, fixing this problem.