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
|
