[AstroPy] Documentation Guidelines

Joe Harrington jh at physics.ucf.edu
Mon Jul 11 14:23:13 EDT 2011

I apologize profusely for replying on the wrong thread!  I've
re-posted here so discussion can follow in the right one.  Sorry for
the extra traffic.

> 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:


   If you want to see what the results look like, just type
   help(np.whatever), or look at the PDF or HTML pages at

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


   A description of the workflow and links to the style guidelines,
   templates, and examples are here:


   Source code to pydocweb is here:


   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:


   I hope the community will accept this format and system.  It's


More information about the AstroPy mailing list