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 / [EMAIL PROTECTED] / http://blog.ianbicking.org _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
