more doc work

1 files changed, 59 insertions, 62 deletions

diff --git a/numpy/doc/HOWTO_DOCUMENT.txt b/numpy/doc/HOWTO_DOCUMENT.txt
index 6c1c07b9c..bb2e141e2 100644
--- a/numpy/doc/HOWTO_DOCUMENT.txt
+++ b/numpy/doc/HOWTO_DOCUMENT.txt
@@ -1,34 +1,47 @@
-===========================
-How-to document NumPy/SciPy
-===========================
+=================================
+A Guide to NumPy/SciPy Docstrings
+=================================
 
 .. Contents::
 
 Overview
 --------
 
-(`epydoc <http://epydoc.sourceforge.net/>`__)
-`epydoc <http://epydoc.sourceforge.net/>`__
+A documentation string (docstring) is a string that describes a module,
+function, class, or method definition.  The docstring is a special attribute
+of the object (``object.__doc__``) and, for consistency, is surrounded by
+triple double quotes. 
 
-It is desireable that both NumPy and SciPy follow a convention for docstrings
-that provide for some consistency while also allowing epydoc to produce
-nicely-formatted reference guides. However, such a convention has not yet
-been decided on. This is my current thinking on the topic.  If you have
-suggestions for improvements, post them on the numpy-dev list together with
-the epydoc output so they may be discussed.
+Obviously, it is highly desireable that both NumPy and SciPy follow a common
+convention for docstrings that provide for consistency while also allowing
+epydoc to produce nicely-formatted reference guides.  This document describes
+the current community consensus for this standard.  If you have suggestions
+for improvements, post them on the numpy-dev list together with the epydoc
+output so they may be discussed.
 
-The docstring format uses reST syntax as interpreted by epydoc. The markup
-in this proposal is as basic as possible and in particular avoids the use of
-epydoc consolidated fields. This is both because there are a limited number
-of such fields, inadequate to our current needs, and because epydoc moves
-the fields to the end of the documentation, messing up the ordering. So here
-standard definition lists are used instead.  Likewise, epydoc moves headings
-and have an unwelcome size in the default style sheet, hence they have also
-been avoided.
+Our docstring standard uses `reST <http://docutils.sourceforge.net/rst.html>`__
+syntax and is rendered using `epydoc <http://epydoc.sourceforge.net/>`__. The
+markup in this proposal is as basic as possible and in particular avoids the
+use of epydoc consolidated fields. This is both because there are a limited
+number of such fields, inadequate to our current needs, and because epydoc
+moves the fields to the end of the documentation, messing up the ordering. So
+here standard definition lists are used instead.  Likewise, epydoc moves
+headings and have an unwelcome size in the default style sheet, hence they
+have also been avoided.
 
-A maximum line width of 79 is suggested, as this will allow the docstrings to
-display on standard terminals. This convention is a bit old and traces back
-to IBM punchcard days, but still seems to be the standard.
+
+Status
+------
+
+We are currently trying to:
+
+1. Agree on docstring standards.
+
+2. Work with Ed loper to ensure that epydoc provides the functionality we
+need.
+
+3. Convert existing docstrings to the new format and write them for those
+that currently lack docstrings.
 
 
 Sections
@@ -52,50 +65,33 @@ An optional section used to describe little used
 parameters so that functions with a large number of keyword argument can still
 be well documented without cluttering the main parameters' list.
 
-The Other Parameters section is for functions taking a lot of keywords
-which are not always used or neeeded and whose description would clutter then
-main purpose of the function. (Comment by Chuck : I think this should be
-rarely used, if at all)
-
-6. **See also:** An optional section used to refer the reader to other
-related !SciPy code.  This section can be extremely useful, but needs to be
-used with caution.  It can be difficult to maintain and if not used
-judiciously this section can quickly loose its usefulness. For example if a
-function points the reader to each and every other function in the same
-package, it becomes pointless and creates a bunch of similar-looking text that
-will likely get ignored by the reader.  In general, you might want to only
-include references to code that has a very close relationship to the current
-function (e.g., {{{trapz()}}} and {{{cumtrapz()}}}) or if the code you point
-to provides additional information in its docstring that gives more insight
-into what the current function is actually doing.
-
-The See Also section can list additional related functions.  The purpose
-of this section is to direct users to other functions they may not be aware
-of or have easy means to discover (i.e. by looking at the docstring of the
-module).  Thus, repeating functions that are in the same module is not useful
-and can create a cluttered document.  Please use judgement when listing
-additional functions.  Routines that provide additional information in their
+6. **See also:**
+An optional section used to refer to related code.  This section can be
+extremely useful, but needs to be used with caution.  It can be difficult
+to maintain and if not used judiciously this section can quickly loose its
+usefulness.  The purpose of this section is to direct users to other
+functions they may not be aware of or have easy means to discover (i.e.,
+by looking at the docstring of the module).  Thus, repeating functions
+that are in the same module is not useful and can create a cluttered
+document.  Routines that provide additional information in their
 docstrings for this function may be useful to include here.
 
-7. **Notes:** An optional section that provides additional information
+7. **Notes:**
+An optional section that provides additional information
 about the code possibly including a discussion or presentation of the
-algorithm. This section may include mathematical equations possibly written in
-[http://www.latex-project.org/ LaTeX].
-
-The Notes section can contain algorithmic information if that is useful.
-
-8. **Examples:** An optional section for examples using the
-[http://www.python.org/doc/lib/module-doctest.html doctest] format.  It can
-provide an inline mini-tutorial as well as additional regression testing.
-While optional, this section is strongly encouraged.
-
-The Examples section is strongly encouraged.  The examples can provide a
-mini-tutorial as well as additional regression testing. (Comment by Chuck:
+algorithm. This section may include mathematical equations possibly written
+in `LaTeX <http://www.latex-project.org/>`__.
+
+8. **Examples:**
+An optional section for examples using the
+`doctest <http://www.python.org/doc/lib/module-doctest.html>`__ format.  It
+can provide an inline mini-tutorial as well as additional regression testing.
+While optional, this section is strongly encouraged.  (Comment by Chuck:
 blank lines in the numpy output, for instance in multidimensional arrays,
 will break doctest.) You can run the tests by doing::
 
   >>> import doctest
-  >>> doctest.testfile('HOWTO_DOCUMENT.txt')
+  >>> doctest.testfile('example.py')
 
 
 Common reST concepts
@@ -105,9 +101,10 @@ A reST-documented module should define::
 
   __docformat__ = 'restructuredtext en'
 
-at the top level in accordance with PEP 258.  Note that the __docformat__
-variable in a package's __init__.py file does not apply to objects defined in
-subpackages and submodules.
+at the top level in accordance with
+`PEP 258 http://www.python.org/dev/peps/pep-0258>`__.  Note that the
+__docformat__ variable in a package's __init__.py file does not apply to
+objects defined in subpackages and submodules.
 
 For paragraphs, indentation is significant and indicates indentation in the
 output. New paragraphs are marked with blank line.