Re: [Docutils-develop] extractor.py

[Ian B. <ia...@co...>]

After documenting a larger module from Webware, I realized that the
including thing was kind of annoying.  Or, rather, I just found myself
including things in order (or wanting to reorder the definitions).

So, while including is still supported, now all methods and functions
get included automatically.  But intermediate docstrings can be used to
provide commentary, like:

    """
    SomeModule does lots of stuff
    """

    def stuff(): whatever

    """
    The following functions are dangerous!
    """

    def dangerousstuff(): whatever

You can still do .. inline: ..., and that will suppress the automatic
insertion of that function or method.  You can also .. ignore: ... the
function, or put :ignore: in the docstring.  I just realized it should
parse __all__ for hints too -- in most cases anything not in __all__ can
be ignored.  However, some class instances may only be created
indirectly, so there'd have to be a way to override that.  

Anyway, I feel like this brings the extracting into decent shape for
me.  I'll try using it again tomorrow, which will be the real test.  The
next thing I see is dealing with inheritance (since multiple
modules/classes come together to make one interface, and I'd like it
documented centrally but from docstrings that aren't centrally
located).  Then other cross-module references, which I think is still an
open issue for reST...?

Altogether, though, things seem to be coming together fairly well.

-- 
Ian Bicking           Colorstudy Web Development
ia...@co...   http://www.colorstudy.com
PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7
4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241