[Doc-SIG] Python docs in reST
ianb at colorstudy.com
Wed May 18 18:20:44 CEST 2005
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
More information about the Doc-SIG