Selective HTML doc generation

[Brian van den Broek]

Graham said unto the world upon 2005-02-23 09:42:
> Hi. I'm looking for a documentation generation tool (such as pydoc,
> epydoc, happydoc, etc.) that will allow me to filter what it includes
> in
> it's output.
> 
> I only want the reader to know about classes and methods in my package
> if if the classes have docstrings. I've got a large package that is
> used
> by relatively non-technical users (and yet they write Python!) that
> documents the public API with docstrings. I don't want to clutter their
> view of the world with links to the package's internal classes and
> documentation that covers things like __special__ methods.
> 
> Anybody know of anything that let's you do it? I realise I may end up
> doing some hacking here but don't want to repeat work unnecessarily.
> 
> Cheers,
> 
> Graham

Hi Graham,

<Warning> I'm not at all an expert </Warning>

OK, that out of the way:

I recently wanted pydoc to display information about my methods whose 
names started with one or more underscores, so that I could see in the 
docs for the objects in my first bigger than small project.

I managed with a small change to the visiblename function of pydoc.py.
It looks to me that this is also the place where you'd want to put in 
code to filter for only treating objects with docstrings. *How* to do 
that is something I've not read enough of pydoc.py to speak to.

Omitting special methods is easy, though. The code says:
     # Private names are hidden, but special names are displayed.
     if name.startswith('__') and name.endswith('__'): return 1
So, just change the 1 to a 0. (The `private' logic is a few lines 
down.) Easy :-)

Hope that is at least of some help. Best,

Brian vdB