[Doc-SIG] Python docs in reST

[Ian Bicking]

Michael Foord wrote:
> You could overcome these problems by parsing source code rather than 
> importing and examining objects. You would obviously need to develop 
> appropriate conventions.
> 
> I don't object to using a magic variable like '__manual__' - but I would 
> want to obtain it by parsing rather than introspection. (In which case 
> you could equally use a docstring at the end of a document).
> 
> In either case it would need work recommencing on the Pysource reader. 
> I'm working on rest2web at the moment - but will have some time in the 
> future to look at this - I do want to get further into the docutils 
> source code.

Personally I thought source parsing was the right thing too -- it makes 
some things easier, like detecting top-level strings, which can be 
treated like interstitial docstrings.  But since then I've changed my 
mind, and prefer introspection.

It allows some things that source parsing doesn't allow at all, like 
generating documentation programmatically.  I think this is important 
for code that uses frameworks, as there's often very structured 
information about the code that is best expressed in Python data 
structures.  It also allows code that effectively does domain-specific 
introspection to create documentation.

Another issue is that Python source is becoming increasingly dynamic 
(both because of extensions to Python and because the Python community 
has generally been using more metaprogramming techniques).  For 
instance, you can't really figure out what a decorator will do until you 
actually run it.  We don't have good conventions right now for how a 
decorator actually could add information to the documentation, but any 
convention we could make will have to rely on object introspection 
instead of source parsing.

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