[Numpy-svn] r4127 - trunk/numpy/doc
Tue Sep 25 05:39:53 CDT 2007
Date: 2007-09-25 05:39:34 -0500 (Tue, 25 Sep 2007)
New Revision: 4127
Update formatting. Mention how to handle blank lines in doctests.
--- trunk/numpy/doc/HOWTO_DOCUMENT.txt 2007-09-25 10:36:11 UTC (rev 4126)
+++ trunk/numpy/doc/HOWTO_DOCUMENT.txt 2007-09-25 10:39:34 UTC (rev 4127)
@@ -10,24 +10,25 @@
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.
+triple double quotes.
-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.
+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-discussion list`_, together with the epydoc output.
-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.
+Our docstring standard uses `reST
+<http://docutils.sourceforge.net/rst.html>`__ syntax and is rendered
+using 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. Standard definition
+lists are used instead. Likewise, epydoc moves headings and have an
+unwelcome size in the default style sheet, therefore they are also
@@ -37,11 +38,11 @@
1. Agree on docstring standards.
-2. Work with Ed loper to ensure that epydoc provides the functionality we
+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.
+3. Convert existing docstrings to the new format and write them for
+ those that currently lack docstrings.
@@ -50,50 +51,60 @@
The proposed sections of the docstring are:
1. **Short summary:**
-A one-line summary not using variable names or the function name (unless a
+ A one-line summary not using variable names or the function name
+ (unless a C-function).
2. **Extended summary:**
-A few sentences giving an extended description.
+ A few sentences giving an extended description.
+ Description of the function arguments, keywords and their
+ respective types.
+ Explanation of the returned values and their types.
5. **Other parameters:**
-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.
+ 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.
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.
+ An optional section used to refer to related code. This section
+ can be very useful, but should be used judiciously. The goal is to
+ direct users to other functions they may not be aware of, or have
+ easy means of discovering (by looking at the module docstring, for
+ example). Routines whose docstrings further explain parameters
+ used by this function are good candidates.
-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 `LaTeX <http://www.latex-project.org/>`__.
+ An optional section that provides additional information about the
+ code, possibly including a discussion of the algorithm. This
+ section may include mathematical equations, possibly written in
+ `LaTeX <http://www.latex-project.org/>`__.
-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::
+ 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. You can run the tests by doing::
- >>> import doctest
- >>> doctest.testfile('example.py')
+ >>> import doctest
+ >>> doctest.testfile('example.py')
+ Blank lines are used to seperate doctests. When they occur in the
+ expected output, they should be replaced by ``<BLANKLINE>`` (see
+ `doctest options
+ <http://docs.python.org/lib/doctest-options.html>`_), e.g.
+ >>> print "a\n\nb"
Common reST concepts
@@ -101,10 +112,10 @@
__docformat__ = 'restructuredtext en'
-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.
+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.
@@ -123,12 +134,11 @@
+Currently, we recommend that you build epydoc from the trunk::
-Currently we recommend that you build eydoc from the trunk::
svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
sudo python setup.py install
@@ -156,18 +166,27 @@
-Here is a short example module in
+Here is a short example module,
`plain text <http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>`__
+`rendered <http://www.scipy.org/doc/example>`__ in HTML.
To try this yourself, simply download the example.py::
svn co http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py .
-You can run epydoc on this file like so::
+Then, run epydoc::
$ epydoc example.txt
-The output will be in a directory named html in the same directory as this
-document and may be viewed by loading the index.html file into your browser.
+The output is placed in ``./html``, and may be viewed by loading the
+``index.html`` file into your browser.
+This document itself was written in ReStructuredText, and may be converted to
+ $ rst2html HOWTO_DOCUMENT.txt HOWTO_DOCUMENT.html
+.. _SciPy: http://www.scipy.org
+.. _numpy-discussion list: http://www.scipy.org/Mailing_Lists
+.. _epydoc: http://epydoc.sourceforge.net/
More information about the Numpy-svn