[cctbxbb] Sphinx docs for CCTBX

[Nigel Moriarty]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20140819/5535a0df/attachment.htm>