Re: [cctbxbb] Sphinx docs for CCTBX

These links don't work for me. On Mon, Aug 18, 2014 at 3:16 PM, Ian Rees wrote:

I'm using a separate build configuration for the docs. You can view the nightly results here:

http://cci-vm-6.lbl.gov:8010/builders/cctbx%2Bdocs-linux-64

If you click the first build, you can view the log files for each step, and view the Sphinx log file by clicking "docs:cctbx stdio", e.g.

http://cci-vm-6.lbl.gov:8010/builders/cctbx%2Bdocs-linux-64/builds/6/steps/d...

I'm working through the warnings now. Mostly missing references and import errors.

Ian

On Fri, Aug 15, 2014 at 8:37 AM, Nathaniel Echols wrote:

...

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

-- Nigel W. Moriarty Building 64R0246B, Physical Biosciences Division Lawrence Berkeley National Laboratory Berkeley, CA 94720-8235 Phone : 510-486-5709 Email : [email protected] Fax : 510-486-5909 Web : CCI.LBL.gov