[AstroPy] Coding Guidelines draft (comments encouraged)
Joe Harrington
jh at physics.ucf.edu
Mon Jul 11 01:10:39 EDT 2011
> http://astropy.wikispaces.com/Astropy+Coding+Guidelines
I would strongly encourage:
1. Use the numpy docstring format. We spent a *lot* of time designing
this format and getting community feedback to ensure that projects
like this one can use it, in addition to the core numpy doc
project. It's been vetted in the writing of over 1000 pages of
docs. It can handle images, formulae, and cross references and
there are guidelines for how to do that and how to make sure that
the ASCII version is also sensible. It's what numpy and scipy
users are now used to. It's based on Sphinx, so it makes a PDF,
HTML, and of course ASCII, has doctests, etc. There's a place for
references, and a way to separate the basic info everyone needs to
know from the details ("notes") only specialists care about. There
is one mod that the Matplotlib folks have, for the special case of
families of routines that have dozens or hundreds of identical,
optional parameters (common for graphics routines).
Important: Keep the one-line summary truly to less than about 60
characters. It can be used to make lists of routines, one line per
routine, including the name, for easy indexing. This breaks if the
"one line" goes on and on.
Here is the standard:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
If you want to see what the results look like, just type
help(np.whatever), or look at the PDF or HTML pages at
docs.scipy.org.
2. Use the docs.scipy.org wiki system, pydocweb. Make a project
either there or on the astropy system; the code is OSS. This will
allow normal users who would not otherwise have access to the code
repo to submit doc fixes, examples, and tests; perform peer review;
and discuss specific pages. This is extremely helpful if the
programmer is lazy (or even functionally illiterate ;-), or when
importing a package that's already written and has poor docs (e.g.,
numpy 3 years ago). It can sync in both directions with the VCS,
gives metrics of who contributed what, what needs editing now, what
got worked on this week, etc. You can see who wrote what, and
revert if there's a problem. Check out these features at
http://docs.scipy.org/numpy/
A description of the workflow and links to the style guidelines,
templates, and examples are here:
http://docs.scipy.org/numpy/Front%20Page/
Source code to pydocweb is here:
http://code.google.com/p/pydocweb/
The project at numpy is fairly dormant now, the main docs having
been written (the community fell flat on its face and didn't step
up to review), but the folks are all available on the scipy-dev
mailing list if you want to ask questions about it. The main
developer is Pauli Virtanen. We wrote status articles in the 2008
and 2009 SciPy Conference proceedings:
http://conference.scipy.org/proceedings/SciPy2008/paper_7/
http://conference.scipy.org/proceedings/SciPy2009/paper_14/
I hope the community will accept this format and system. It's
field-tested!
--jh--
More information about the AstroPy
mailing list