[Epydoc-devel] Exclusion lists

[Daniele V. <dan...@gm...>]

Hello Edward,

i added to the Epydoc docbuilder the possibility to skip parsing and 
introspection of submodules whose dotted name matches a given regular 
expression pattern.

While working at the patch, i noticed that it is useful to specify two 
distinct patterns: one for the modules not to be parsed and one for the 
modules not to be introspected. The reason is that too much magic 
modules can  wreck havoc in the built documentation state if imported. 
For example, while i was testing the Twisted package API generation, i 
have been struggling with an object (SelectReactor) reaching the 
indexing phase without a canonical_name assigned... until i noticed the 
very peculiar 'twisted.internet.reactor' module, whose content can be 
summarized into:

     del sys.modules['twisted.internet.reactor']
     #from twisted.python import log
     #log.msg("Installing SelectReactor, since unspecified.")
     from twisted.internet import selectreactor
     selectreactor.install()

This module can be parsed without any problem; if imported instead it 
tries to saw the branch it is sitting on, doing no good to Epydoc state.

In my current working copy, the Twisted API can be completely generated 
using the command line:

     epydoc twisted \
         --exclude-introspect="\.test|\.internet\.reactor" \
         --exclude-parse="\.test"

But now there are 4 different options, all dealing with what to 
elaborate: --introspect-only, --parse-only and the newly added 
--exclude-introspect and --exclude-parse.

I propose to merge them into two options: --no-parse and 
--no-introspect, both with an optional parameter being the pattern to be 
excluded. If the pattern is omitted, --no-parse works as 
--introspect-only and vice-versa.

IIRC optparse doesn't natively handle options with an optional 
parameter, but it is easy to extend it with an option callback [1]: i 
already did stuff like this, es. in http://tinyurl.com/226mtj

I can keep --introspect-only and --parse-only as undocumented options 
doing the right thing but issuing a warning (we still have time to alter 
the command line syntax while in alpha phase, don't we?).

Regards,

Daniele

[1] http://docs.python.org/lib/optparse-option-callbacks.html