Selective HTML doc generation

[Graham]

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

[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

[Graham Ashton]

Thanks Brian, much appreciated. Looks quite straightforward.

Graham

[Brian van den Broek]

Graham Ashton said unto the world upon 2005-02-24 04:54:

Thanks Brian, much appreciated. Looks quite straightforward.

Graham

Hi Graham,

glad it helped -- I think this marks the first time I've given a
useful answer to a non-trivial question on comp.lang.python. :-)

<context for future thread readers>

G: 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.

B:
Pointed Graham to to the visiblename function of pydoc.py, where I
recently made a small change to get it to display `private' methods,
and hypothesized that would be where he'd want to start in order to
modify pydoc to meet his needs.
</context for future thread readers>

Before I responded, I tried for a bit to write the code to filter for
only those objects with docstrings like you wanted. I'm fairly new to
programming and wasn't able to work out exactly what code is needed.
(My skill level is such that it isn't quite so straight-forward to me :-)

Would you be willing to post what you did to make it work? I think I'd
learn something, having bounced off when making a (gentle) push on the
problem.

Best,

Brian vdB