Thanks a lot Nat, Nader, Oliver and Ian, that looks like a good start and hopefully it will motivate more of us to gradually contribute bits of documentation here and there.

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?

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.

Cheers,

Richard

On 13 August 2014 16:13, Nathaniel Echols <nechols@lbl.gov> wrote:

Thanks to some superb work by Nader Morshed, Oliver Zeldin, and Ian Rees, we now have automatically updated Sphinx docs for CCTBX:

http://cci.lbl.gov/cctbx_docs/

Obviously these are still pretty sparse - right now most of the formal documentation is clustered here:

libtbx
libtbx.utils
libtbx.phil (mostly re-using Ralf's old documentation)

cctbx.miller
iotbx.pdb (built on Ralf's newsletter article)
mmtbx.command_line

These are a combination of inline docstrings and separate restructured text files in cctbx_project/sphinx. We have automatically generated rst files for some modules, but others will need to be added manually. In the end I think we'll want to curate every file, but the current layout will get us started. To facilitate additional contributions, I've modifed the installation script for base packages to include a --sphinx option. After setting up CCTBX you can then do this:

cd $BUILD
libtbx.configure sphinx
cd $SRC/cctbx_project/sphinx
make html

and you will get the full documentation built locally. I am still figuring out how to use Sphinx effectively; it is definitely possible to document Boost.Python extensions but it's not quite as obvious.

I don't expect us to retroactively document several hundred thousand lines of code written over a decade, but if we can get the core parts thoroughly covered that will greatly reduce the barrier for new developers. Suggestions for particular modules to focus on are appreciated; I am going to try to cover the basic PDB+reflection file functionality. I encourage anyone doing CCTBX-related development to contribute as you go. (They don't need to be your own APIs, just modules you're reasonably familiar with.) Those of you who already have a ton of undocumented code can expect me to harass you periodically about fixing this.

(Note that I've cannibalized at least one newsletter article for this, and continue to do so; we should re-use existing prose descriptions as much as possible without violating copyrights.)

-Nat

_______________________________________________
cctbxbb mailing list
cctbxbb@phenix-online.org
http://phenix-online.org/mailman/listinfo/cctbxbb