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
-- http://mail.python.org/mailman/listinfo/python-list
