[Doc-SIG] paste.docsupport (was: Python docs in reST)

[Ian Bicking]

(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 
extractor (HTTPExtractor).

> 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 
> difference).

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 
neat.

> 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 
attributes.

-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org