[Doc-SIG] paste.docsupport (was: Python docs in reST)
ianb at colorstudy.com
Fri May 27 18:10:29 CEST 2005
(I thought I'd reply back on-list, since this is still about documentation)
Michael Foord wrote:
> I've had a *quick* look at the paste docsupport. The output looks nice -
> but the code looks tied to the paste framework.
> I have a couple of questions I hope you don't mind (I'm considering
> implementing something myself - but don't want to duplicate something
> you'd do better :-).
> Is your docsupport *specific* to paste - or *could* it work with other
> modules ?
Right now there's no separation of modules for the Paste and generic
code, but the objects are fairly partitioned between the two. There are
some Paste-specific DocItem subclasses in docsupport.metadata; it's my
expectation that any framework will require domain-specific metadata,
and stuff like WSGIKey are examples of that. There's also one custom
> Does it produce standalone references for modules ? Could it be hacked
> to support pulling out *specific* docstrings ? (I'd like to code a
> convention in my reST docs - that allows for the referencing of specific
> docstrings. That way I can produce documentation around my docstrings
> rather than have my docstrings *as* documentation - if you see the
Right now you run the extract.py module and pass in a package or module
name. It creates a single document right now, but I'd definitely like
to make it create a tree of files in the future, and probably
automatically create a file that includes from that tree as well, as a
kind of minimal fully-automated reference doc -- but you could include
those same files into other documents as well.
From there it would be really nice to have a link from the including
document (with the docstring in isolation) to the larger reference
document (that was organized by module), and from there to the actual
source (maybe a highlighted source with lots of id tags). That would be
> Does it use any conventions in the docstrings to produce the output - or
> does it just take the function (class, method etc) name and parameters
> and docstrings - with no additional processing ?
Right now there's no additional processing. If you look in
docsupport.extract there's individual classes to create the formatting
of different types of objects. E.g., MethodExtractor (which should
probably be named FunctionExtractor) does the functions. You could
register different implementations, or subclass the ones that are there.
And actually though the docstring is treated like an opaque item
currently, extractors look at other things. For example, you can do::
def blah(self, *args, **kw):
return self.wrapped(*args, **kw)
blah.proxy = 'wrapped'
And the signature in the docs should match the signature for wrapped.
wsgilib.interactive is an example of this. The attribute 'returns' is
also searched for a return type -- well, actually just any documentable
object (or string reference to an object) which gets inlined in the docs.
Right now I'm not doing any real inspection of the docstrings; I haven't
felt the need yet, and I'm not sure what distinctions I'll need to make.
But at some point I'm sure it will be necessary. Most of the
annotation so far has gone into more transparent structures, like
Ian Bicking / ianb at colorstudy.com / http://blog.ianbicking.org
More information about the Doc-SIG