[cctbxbb] Docstrings and online reference

[Jan Marten Simons]

Hi all,

as you might have noticed I started to add some docstrings to functions. The 
purpose of those is to give a user of the toolbox an idea of this:
1. What's the purpose of the object (function/method/class/...)?
2. What objects should be thrown at it as input/keyword arguments?
3. What kind of object does one get as return value?
I try to extract the information only from the source code, so it's possible 
that I sometimes don't get it right, as I'm just starting to explore the inner 
workings of the toolbox and esp. phenix related parts are (yet) quite obscure 
for me.

I'm trying to document objects in a consistent way, so that a user (as well as 
ourself) doesn't get confused. I invite you all to adapt the scheme for new 
functions/objects you code and request comments on further improving it before 
extending its use, so that it's useful and to your likeing as well.
A current example of one such docstring:

def set_u_iso(self, value = None, values = None, selection = None):
  """Set isotropic mean thermic displacements of scatterers

  Input:
  value -- (optional) a single double value to set all u_iso of selected 
scatterers to
  values -- (optional) an array of double values to set all u_iso of selected 
scatterers to
  selection -- (optional) an array of bools to select scatterers to be updated 
with new u_iso values

  Returns: cctbx.xray.structure
  """
  [...]

During my first pass I noticed some already existing docstrings which are also 
shown in the online docs at e.g.
http://cctbx.sourceforge.net/current/python/cctbx.xray.structure.html.
Are those pages automatically generated via a cronjob or does it take a manual 
update to get this information up2date?

Cheers,
Jan