[cctbxbb] Sphinx docs for CCTBX
Nathaniel Echols
nechols at lbl.gov
Wed Aug 13 08:13:45 PDT 2014
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://phenix-online.org/pipermail/cctbxbb/attachments/20140813/284b99f5/attachment.htm>
More information about the cctbxbb
mailing list