Printing Docstrings Without Importing

[Fuzzyman]

Bengt Richter wrote:
> On 1 Aug 2005 06:50:23 -0700, "Fuzzyman" <fuzzyman at gmail.com> wrote:
>
> >This seems to scratch several people's itches.
> >
> >Care to develop/maintain it ?
> >
> Are you talking to me? ;-)
>
> (My news server is having some problem. I saw my post on google groups
> but my normal news client isn't seeing it.)
>
> Assuming you are talking to me, there's a bug, naturally, in trying to
> escape None as a doc string. It was twenty minutes of hacking and a half hour
> of trying to choose html colors, so there's not that much there ;-)
> But what did you have in mind? Javascript menu rollovers for popup docs of
> functions and classes and methods etc? Full help info access? Optional pdf output?
>
> That would take more than another hour, but I did fix the mentioned bug and put
> a table of clickable module names at the top with the file date stamps and paths
> so you can navigate down to the spcific module docstring output quickly if you have
> a lot of them. Of course, I think I'd put styling in the header rather than hack
> more raw html if I were to go another round.
>
> I'll post the latest once I can see my postings in context with my own newsreader again.
>

Hello Brengt,

Sorry - I know it was a very terse reply. The state of automatic API
documentation generating tools is not very good in Python. Epydoc is
the best - but *seems* to be unmaintained. Many people find they can't
use it, because it imports code. Your approach of compiling the code
and introspecting the objects seems like the best alternative.

Some people argue against automatic API documentation *anyway* - but if
you write your docstrings intending them to be useful then it can save
a lot of work. However for a medium sized project, something like
Epydoc that shows the relationship between objects and links the doc
pages appropriately, can be very useful.

This is obviously a lot more work than just generating output for a
single modules.

Anyway - it's a subject that comes up regularly, and I haven't looked
into all the issues. There was some discussion on doc-sig about it a
while back.

All the best,


Fuzzy
http://www.voidspace.org.uk/python

> Regards,
> Bengt Richter