[AstroPy] Documentation Guidelines

[Michael S. Kelley]

Hi all,

I agree with the strong encouragement and arguments for the numpy
docstring format.  In addition to the fact that the numpydoc format is
what numpy and scipy users are used to reading, it will also be
frequently encountered by astropy users when they read the numpy/scipy
documentation (and, to some extent, matplotlib).  I also find the
numpydoc format easy to parse and understand in the on-line help
(i.e., via python help() or ipython "?").

I think the alternate format discussed by Erik T. and Prasanth is OK,
and I've encountered it before (e.g., while reading the AstroLibCoords
documentation).  However, I think this format is more cumbersome to
read because the use of the additional ":param" or ":returns" at the
beginning of each variable definition, and the use of ":type".  For
me, these phrases make the text more difficult to quickly search and
find the variable name that I would be looking for when using the
on-line help.  numpydoc's headings "Parameters", "Returns", etc. is
much easier to read.

- Mike

On Mon, Jul 11, 2011 at 2:23 PM, Joe Harrington <jh at physics.ucf.edu> wrote:
> 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:
>
>   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--
>
>
>
> _______________________________________________
> AstroPy mailing list
> AstroPy at scipy.org
> http://mail.scipy.org/mailman/listinfo/astropy
>
>



-- 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Michael S Kelley
Department of Astronomy
University of Maryland -- College Park
301-405-3796