On Fri, Aug 15, 2014 at 8:06 AM, Richard Gildea <rgildea@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