[cctbxbb] Python documentation
dgwaterman at gmail.com
Mon Oct 8 08:17:52 PDT 2012
I found one here after some random browsing:
*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.
On 8 October 2012 16:01, Luc Bourhis <luc_j_bourhis at mac.com> wrote:
> Hi David,
> I've got a few questions about the automatically generated Python
> 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,
> cctbxbb mailing list
> cctbxbb at phenix-online.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the cctbxbb