[cctbxbb] Sphinx docs for CCTBX

[Nathaniel Echols]

On Fri, Aug 15, 2014 at 8:06 AM, Richard Gildea <rgildea at gmail.com> wrote:

> I had a go at starting to document cctbx.uctbx.unit_cell, which as you
> know is mainly a Boost.Python extension (
> https://sourceforge.net/p/cctbx/code/20467/). Before I travel too much
> further down this route, is this an appropriate way of documenting
> Boost.Python extensions or is there a better way we can do this?
>

I haven't had enough time to experiment to decide on the best approach.  I
see three choices - the first is what you've done:

class my_class (ext.my_class) :
  """doc"""

  def boosted_function (self, some_argument) :
    """function doc"""
    super(ext.my_class, self).boosted_function(some_argument)

OR (2):

ext.my_class.__doc__ = """doc"""
ext.my_class.boosted_function.__func__.__doc__ = """function doc"""

OR (3):

put the docstrings in C++ code, for instance:

.def("boosted_function", &my_class::boosted_function, "function doc")

(not sure what the equivalent is for classes but it's probably pretty
similar)

My opinion is that (1) is much too prone to confusion and API conflicts
unless we're already using this code structure (and FYI, you broke the call
signatures for a couple of methods).  (3) is just gross.  (2) is also gross
but has the virtue of being the least likely to break, and doesn't require
modifying C++ files.  So I'm inclined to take that approach

(For what it's worth, when modifying a class using the boost.python
injector, we appear to be able to set __doc__ inside there; see
iotbx.pdb.hierarchy for an example.)

It would be good to get the documentation for the core cctbx classes up and
> running, however several of the core classes (e.g. cctbx.sgtbx.space_group,
> cctbx.uctbx.unit_cell, flex arrays) are mostly Boost.Python extensions, so
> it would be good to arrive at a sensible way to document these extensions.
>

Agreed.  I think for flex arrays we will be stuck writing the docstrings in
C++ - however since these are relatively stable APIs it should be
reasonably straightforward.

-Nat
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20140815/19a8681f/attachment.htm>