[cctbxbb] Sphinx docs for CCTBX

[Richard Gildea]

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 at 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 at phenix-online.org
> http://phenix-online.org/mailman/listinfo/cctbxbb
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20140815/ef9c1f8f/attachment.htm>