<div dir="ltr">These links don't work for me.</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Aug 18, 2014 at 3:16 PM, Ian Rees <span dir="ltr"><<a href="mailto:irees@lbl.gov" target="_blank">irees@lbl.gov</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I'm using a separate build configuration for the docs. You can view<br>
the nightly results here:<br>
<br>
<a href="http://cci-vm-6.lbl.gov:8010/builders/cctbx%2Bdocs-linux-64" target="_blank">http://cci-vm-6.lbl.gov:8010/builders/cctbx%2Bdocs-linux-64</a><br>
<br>
If you click the first build, you can view the log files for each<br>
step, and view the Sphinx log file by clicking "docs:cctbx stdio",<br>
e.g.<br>
<br>
<a href="http://cci-vm-6.lbl.gov:8010/builders/cctbx%2Bdocs-linux-64/builds/6/steps/docs%3Acctbx/logs/stdio" target="_blank">http://cci-vm-6.lbl.gov:8010/builders/cctbx%2Bdocs-linux-64/builds/6/steps/docs%3Acctbx/logs/stdio</a><br>
<br>
I'm working through the warnings now. Mostly missing references and<br>
import errors.<br>
<span class="HOEnZb"><font color="#888888"><br>
Ian<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
On Fri, Aug 15, 2014 at 8:37 AM, Nathaniel Echols <<a href="mailto:nechols@lbl.gov">nechols@lbl.gov</a>> wrote:<br>
> On Fri, Aug 15, 2014 at 8:06 AM, Richard Gildea <<a href="mailto:rgildea@gmail.com">rgildea@gmail.com</a>> wrote:<br>
>><br>
>> I had a go at starting to document cctbx.uctbx.unit_cell, which as you<br>
>> know is mainly a Boost.Python extension<br>
>> (<a href="https://sourceforge.net/p/cctbx/code/20467/" target="_blank">https://sourceforge.net/p/cctbx/code/20467/</a>). Before I travel too much<br>
>> further down this route, is this an appropriate way of documenting<br>
>> Boost.Python extensions or is there a better way we can do this?<br>
><br>
><br>
> I haven't had enough time to experiment to decide on the best approach. I<br>
> see three choices - the first is what you've done:<br>
><br>
> class my_class (ext.my_class) :<br>
> """doc"""<br>
><br>
> def boosted_function (self, some_argument) :<br>
> """function doc"""<br>
> super(ext.my_class, self).boosted_function(some_argument)<br>
><br>
> OR (2):<br>
><br>
> ext.my_class.__doc__ = """doc"""<br>
> ext.my_class.boosted_function.__func__.__doc__ = """function doc"""<br>
><br>
> OR (3):<br>
><br>
> put the docstrings in C++ code, for instance:<br>
><br>
> .def("boosted_function", &my_class::boosted_function, "function doc")<br>
><br>
> (not sure what the equivalent is for classes but it's probably pretty<br>
> similar)<br>
><br>
> My opinion is that (1) is much too prone to confusion and API conflicts<br>
> unless we're already using this code structure (and FYI, you broke the call<br>
> signatures for a couple of methods). (3) is just gross. (2) is also gross<br>
> but has the virtue of being the least likely to break, and doesn't require<br>
> modifying C++ files. So I'm inclined to take that approach<br>
><br>
> (For what it's worth, when modifying a class using the boost.python<br>
> injector, we appear to be able to set __doc__ inside there; see<br>
> iotbx.pdb.hierarchy for an example.)<br>
><br>
>> It would be good to get the documentation for the core cctbx classes up<br>
>> and running, however several of the core classes (e.g.<br>
>> cctbx.sgtbx.space_group, cctbx.uctbx.unit_cell, flex arrays) are mostly<br>
>> Boost.Python extensions, so it would be good to arrive at a sensible way to<br>
>> document these extensions.<br>
><br>
><br>
> Agreed. I think for flex arrays we will be stuck writing the docstrings in<br>
> C++ - however since these are relatively stable APIs it should be reasonably<br>
> straightforward.<br>
><br>
> -Nat<br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br>Nigel W. Moriarty<br>Building 64R0246B, Physical Biosciences Division<br>Lawrence Berkeley National Laboratory<br>Berkeley, CA 94720-8235<br>Phone : 510-486-5709 Email : NWMoriarty@LBL.gov<br>
Fax : 510-486-5909 Web : <a href="http://CCI.LBL.gov">CCI.LBL.gov</a>
</div>