Hi David,
I've got a few questions about the automatically generated Python documentation.
1. Is this done by doxygen like the C++ documentation?
No. It has traditionally been generated with pydoc. A few years back, Jan Marten Simons added generation with sphinx, which gives much better looking html pages.
2. What are the rules that determine whether text in source files is included as documentation or not? Clearly docstrings are, but also some comments do (only those at module scope?)
As far as I know, only docstrings should be gathered by pydoc or sphinx. Could you give me an example of those other comments?
3. Similarly, what determines which packages are documented or not? For example, from http://cctbx.sourceforge.net/current/python/rstbx.html, cftbx is documented but bpcx is not. Is there at some point a manual decision about what should be documented?
No. Some developers like to put quite a bit of comments, other don't bother. It also depends on how much in a hurry the developer is of course as documentation does nothing to help reaching a dead line. Best wishes, Luc