How does pydoc parse code?

[Michael Hudson]

greg at conifold.math.ucdavis.edu (Greg Kuperberg) writes:

> I plan to use pydoc for my Python project.  After looking through the
> standard documentation, I am not sure how pydoc interprets its input.
> In its basic operation it evidently looks at the first string literal in
> the module and in each function definition.  But there is more to the
> story than that, obviously.  What other vestigial code does it detect?
> Every string literal?  Variables of the form __xxx__, I gather?  Which of
> these variables have a special meaning?  How does it divide the initial
> string literal into the "name" and "description" sections?  What other
> directives can I send to pydoc to alter its presentation?

It would be nice if there was a concise, simple place in the
documentation I could point you to to answer that question.

Alas, it does what it does, and that's about all that can be said.

Oh, and it *doesn't* parse the module: it imports and then introspects
it.

> For instance, I might want a revision history for each module listed
> before the description.  Is there a way to do that?  Or I might want
> to suppress the __xxx__ variables used by pydoc from the data section.
> Is there a way to do that?  What *can* I do?

Beats me.  You might be happier with one of the other documentation
tools like epydoc or happydoc (both at SF) but I know very little
about them...

Cheers,
mwh

-- 
  > I'm a little confused.
  That's because you're Australian!  So all the blood flows to
  your head, away from the organ most normal guys think with.
                        -- Mark Hammond & Tim Peters, comp.lang.python