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/docs%3Acctbx/logs/stdio

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 <nechols@lbl.gov> wrote:
> 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