Hi Nat, Thanks. I'm not desperate to see updated docs, just to get an idea of how to proceed. But it sounds as though regeneration is about due anyway. Cheers -- David On 8 October 2012 14:47, Nathaniel Echols wrote:

On Mon, Oct 8, 2012 at 3:48 AM, David Waterman wrote:

...

I've got a few questions about the automatically generated Python documentation. ... 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?

I think the partial answer is that the while the documentation is automatically generated, it is only updated on demand - i.e. someone needs to run a script to rebuild the online docs. Not surprisingly, this hasn't been done since at least May. I'll see if I can figure out how to do this today (which may help answer the other questions).

-Nat _______________________________________________ cctbxbb mailing list [email protected] http://phenix-online.org/mailman/listinfo/cctbxbb

Hi Luc, I found one here after some random browsing: http://cctbx.sourceforge.net/current/python/rstbx.viewer.html, i.e. *get_intensities_in_box*(self, x, y, boxsize=400, mag=16) # XXX does this need to be in C++? which looks to me like it comes from rstbx/viewer/__init__.py. But it may just be that the code has changed since the last documentation run. I don't suppose this is a problem, I'm just trying to understand what the rules are when the code is scraped for docs. Cheers -- David On 8 October 2012 16:01, Luc Bourhis wrote:

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

_______________________________________________ cctbxbb mailing list [email protected] http://phenix-online.org/mailman/listinfo/cctbxbb

On Mon, Oct 8, 2012 at 8:38 AM, Luc Bourhis wrote:

# XXX does this need to be in C++? def get_intensities_in_box (self, x, y, boxsize=400, mag=16) :

I would not have thought that this comment would be picked up as if it was a docstring for that function.

I suspect the documentation software treats comments which include XXX specially. Anyway, I have now updated the web site with current documentation, aside from the dozen or so modules which raise errors (usually because of missing modules); looks like most of rstbx is now covered. I'll try to do this semi-regularly in the future. -Nat