[cctbxbb] Python documentation

David Waterman dgwaterman at gmail.com
Mon Oct 8 08:17:52 PDT 2012


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 <luc_j_bourhis at mac.com> 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
> cctbxbb at phenix-online.org
> http://phenix-online.org/mailman/listinfo/cctbxbb
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20121008/68896f4c/attachment.htm>


More information about the cctbxbb mailing list