[cctbxbb] Sphinx docs for CCTBX

[Ian Rees]

The address changed slightly,

http://cci-vm-6.lbl.gov:8010/builders/cctbx-docs-linux-64

and

http://cci-vm-6.lbl.gov:8010/builders/cctbx-docs-linux-64/builds/0/steps/docs%3Acctbx/logs/stdio

It might change again in the future when we finalize the builder
virtual machines, in which case I'll send out the updated link.

Ian

On Tue, Aug 19, 2014 at 6:38 PM, Nigel Moriarty <nwmoriarty at lbl.gov> wrote:
> These links don't work for me.
>
>
> On Mon, Aug 18, 2014 at 3:16 PM, Ian Rees <irees at lbl.gov> 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/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 at lbl.gov> wrote:
>> > 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
>
>
>
>
> --
> Nigel W. Moriarty
> Building 64R0246B, Physical Biosciences Division
> Lawrence Berkeley National Laboratory
> Berkeley, CA 94720-8235
> Phone : 510-486-5709     Email : NWMoriarty at LBL.gov
> Fax   : 510-486-5909       Web  : CCI.LBL.gov