DOC: rename ReST files under doc/ from *.txt to *.rst.txt, so they render on github.

1 files changed, 516 insertions, 0 deletions

diff --git a/doc/HOWTO_DOCUMENT.rst.txt b/doc/HOWTO_DOCUMENT.rst.txt
new file mode 100644
index 000000000..bbd9531e8
--- /dev/null
+++ b/doc/HOWTO_DOCUMENT.rst.txt
@@ -0,0 +1,516 @@
+====================================
+A Guide to NumPy/SciPy Documentation
+====================================
+
+.. Contents::
+
+.. Note::
+
+   For an accompanying example, see `example.py
+   <http://github.com/numpy/numpy/blob/master/doc/example.py>`_.
+
+Overview
+--------
+In general, we follow the standard Python style conventions as described here:
+ * `Style Guide for C Code <http://www.python.org/peps/pep-0007.html>`_
+ * `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_
+ * `Docstring Conventions <http://www.python.org/peps/pep-0257.html>`_
+
+Additional PEPs of interest regarding documentation of code:
+ * `Docstring Processing Framework <http://www.python.org/peps/pep-0256.html>`_
+ * `Docutils Design Specification <http://www.python.org/peps/pep-0258.html>`_
+
+Use a code checker:
+ * `pylint <http://www.logilab.org/857>`_
+ * `pyflakes` easy_install pyflakes
+ * `pep8.py <http://svn.browsershots.org/trunk/devtools/pep8/pep8.py>`_
+
+The following import conventions are used throughout the NumPy source
+and documentation::
+
+   import numpy as np
+   import scipy as sp
+   import matplotlib as mpl
+   import matplotlib.pyplot as plt
+
+It is not necessary to do ``import numpy as np`` at the beginning of
+an example.  However, some sub-modules, such as ``fft``, are not
+imported by default, and you have to include them explicitly::
+
+  import numpy.fft
+
+after which you may use it::
+
+  np.fft.fft2(...)
+
+Docstring Standard
+------------------
+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, i.e.::
+
+   """This is the form of a docstring.
+
+   It can be spread over several lines.
+
+   """
+
+NumPy, SciPy_, and the scikits follow a common convention for
+docstrings that provides for consistency, while also allowing our
+toolchain to produce well-formatted reference guides.  This document
+describes the current community consensus for such a standard.  If you
+have suggestions for improvements, post them on the `numpy-discussion
+list`_.
+
+Our docstring standard uses `re-structured text (reST)
+<http://docutils.sourceforge.net/rst.html>`_ syntax and is rendered
+using Sphinx_ (a pre-processor that understands the particular
+documentation style we are using).  While a rich set of
+markup is available, we limit ourselves to a very basic subset, in
+order to provide docstrings that are easy to read on text-only
+terminals.
+
+A guiding principle is that human readers of the text are given
+precedence over contorting docstrings so our tools produce nice
+output.  Rather than sacrificing the readability of the docstrings, we
+have written pre-processors to assist Sphinx_ in its task.
+
+The length of docstring lines should be kept to 75 characters to
+facilitate reading the docstrings in text terminals.
+
+Status
+------
+We are busy converting existing docstrings to the new format,
+expanding them where they are lacking, as well as writing new ones for
+undocumented functions.  Volunteers are welcome to join the effort on
+our new documentation system (see the `Documentation Editor
+<http://docs.scipy.org/doc/>`_ and the `Developer Zone
+<http://www.scipy.org/Developer_Zone/DocMarathon2008>`_).
+
+Sections
+--------
+The sections of the docstring are:
+
+1. **Short summary**
+
+   A one-line summary that does not use variable names or the function
+   name, e.g.
+
+   ::
+
+     def add(a, b):
+        """The sum of two numbers.
+
+        """
+
+   The function signature is normally found by introspection and
+   displayed by the help function.  For some functions (notably those
+   written in C) the signature is not available, so we have to specify
+   it as the first line of the docstring::
+
+     """
+     add(a, b)
+
+     The sum of two numbers.
+
+     """
+
+2. **Extended summary**
+
+   A few sentences giving an extended description.  This section
+   should be used to clarify *functionality*, not to discuss
+   implementation detail or background theory, which should rather be
+   explored in the **notes** section below.  You may refer to the
+   parameters and the function name, but parameter descriptions still
+   belong in the **parameters** section.
+
+3. **Parameters**
+
+   Description of the function arguments, keywords and their
+   respective types.
+
+   ::
+
+     Parameters
+     ----------
+     x : type
+        Description of parameter `x`.
+
+   Enclose variables in single backticks.  
+
+   For the parameter types, be as preciese as possible.  Below are a
+   few examples of parameters and their types.
+
+   ::
+
+     Parameters
+     ----------
+     filename : str
+     copy : bool
+     dtype : data-type
+     iterable : iterable object     
+     shape : int or tuple of int
+     files : list of str
+
+   If it is not necessary to specify a keyword argument, use
+   ``optional``::
+
+     x : int, optional
+
+   Optional keyword parameters have default values, which are
+   displayed as part of the function signature.  They can also be
+   detailed in the description::
+
+     Description of parameter `x` (the default is -1, which implies summation
+     over all axes).
+
+   When a parameter can only assume one of a fixed set of values,
+   those values can be listed in braces::
+
+     order : {'C', 'F', 'A'}
+         Description of `order`.
+
+   When two or more input parameters have exactly the same type, shape and
+   description, they can be combined::
+
+     x1, x2 : array_like
+         Input arrays, description of `x1`, `x2`.
+
+4. **Returns**
+
+   Explanation of the returned values and their types, of the same
+   format as **parameters**.
+
+5. **Other parameters**
+
+   An optional section used to describe infrequently used parameters.
+   It should only be used if a function has a large number of keyword
+   prameters, to prevent cluttering the **parameters** section.
+
+6. **Raises**
+
+   An optional section detailing which errors get raised and under
+   what conditions::
+
+     Raises
+     ------
+     LinAlgException
+         If the matrix is not numerically invertible.
+
+   This section should be used judiciously, i.e only for errors
+   that are non-obvious or have a large chance of getting raised.
+
+7. **See Also**
+
+   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.
+
+   As an example, for ``numpy.mean`` we would have::
+
+     See Also
+     --------
+     average : Weighted average
+
+   When referring to functions in the same sub-module, no prefix is
+   needed, and the tree is searched upwards for a match.
+
+   Prefix functions from other sub-modules appropriately.  E.g.,
+   whilst documenting the ``random`` module, refer to a function in
+   ``fft`` by
+
+   ::
+
+     fft.fft2 : 2-D fast discrete Fourier transform
+
+   When referring to an entirely different module::
+
+     scipy.random.norm : Random variates, PDFs, etc.
+
+   Functions may be listed without descriptions, and this is
+   preferable if the functionality is clear from the function name::
+
+     See Also
+     --------
+     func_a : Function a with its description.
+     func_b, func_c_, func_d
+     func_e
+
+8. **Notes**
+
+   An optional section that provides additional information about the
+   code, possibly including a discussion of the algorithm. This
+   section may include mathematical equations, written in
+   `LaTeX <http://www.latex-project.org/>`_ format::
+
+     The FFT is a fast implementation of the discrete Fourier transform:
+
+     .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
+
+   Equations can also be typeset underneath the math directive::
+
+     The discrete-time Fourier time-convolution property states that
+
+     .. math::
+
+          x(n) * y(n) \Leftrightarrow X(e^{j\omega } )Y(e^{j\omega } )\\
+          another equation here
+
+   Math can furthermore be used inline, i.e.
+
+   ::
+
+     The value of :math:`\omega` is larger than 5.
+
+   Variable names are displayed in typewriter font, obtained by using
+   ``\mathtt{var}``::
+
+     We square the input parameter `alpha` to obtain
+     :math:`\mathtt{alpha}^2`.
+
+   Note that LaTeX is not particularly easy to read, so use equations
+   sparingly.
+
+   Images are allowed, but should not be central to the explanation;
+   users viewing the docstring as text must be able to comprehend its
+   meaning without resorting to an image viewer.  These additional
+   illustrations are included using::
+
+     .. image:: filename
+
+   where filename is a path relative to the reference guide source
+   directory.
+
+9. **References**
+
+   References cited in the **notes** section may be listed here,
+   e.g. if you cited the article below using the text ``[1]_``,
+   include it as in the list as follows::
+
+     .. [1] O. McNoleg, "The integration of GIS, remote sensing,
+        expert systems and adaptive co-kriging for environmental habitat
+        modelling of the Highland Haggis using object-oriented, fuzzy-logic
+        and neural-network techniques," Computers & Geosciences, vol. 22,
+        pp. 585-588, 1996.
+
+   which renders as
+
+   .. [1] O. McNoleg, "The integration of GIS, remote sensing,
+      expert systems and adaptive co-kriging for environmental habitat
+      modelling of the Highland Haggis using object-oriented, fuzzy-logic
+      and neural-network techniques," Computers & Geosciences, vol. 22,
+      pp. 585-588, 1996.
+
+   Referencing sources of a temporary nature, like web pages, is
+   discouraged.  References are meant to augment the docstring, but
+   should not be required to understand it.  Follow the `citation
+   format of the IEEE
+   <http://www.ieee.org/pubs/transactions/auinfo03.pdf>`_, which
+   states that references are numbered, starting from one, in the
+   order in which they are cited.
+
+10. **Examples**
+
+   An optional section for examples, using the `doctest
+   <http://www.python.org/doc/lib/module-doctest.html>`_ format.
+   This section is meant to illustrate usage, not to provide a
+   testing framework -- for that, use the ``tests/`` directory.
+   While optional, this section is very strongly encouraged.
+
+   When multiple examples are provided, they should be separated by
+   blank lines. Comments explaining the examples should have blank
+   lines both above and below them::
+
+     >>> np.add(1, 2)
+     3
+
+     Comment explaining the second example
+
+     >>> np.add([1, 2], [3, 4])
+     array([4, 6])
+
+   For tests with a result that is random or platform-dependent, mark the
+   output as such::
+
+     >>> import numpy.random
+     >>> np.random.rand(2)
+     array([ 0.35773152,  0.38568979])  #random     
+
+   You can run examples using::
+
+     >>> np.test(doctests=True)
+
+   It is not necessary to use the doctest markup ``<BLANKLINE>`` to
+   indicate empty lines in the output. Note that the option to run
+   the examples through ``numpy.test`` is provided for checking if the
+   examples work, not for making the examples part of the testing framework.
+
+   The examples may assume that ``import numpy as np`` is executed before
+   the example code in *numpy*, and ``import scipy as sp`` in *scipy*.
+   Additional examples may make use of *matplotlib* for plotting, but should
+   import it explicitly, e.g., ``import matplotlib.pyplot as plt``.
+
+   
+Documenting classes
+-------------------
+
+Class docstring
+```````````````
+Use the same sections as outlined above (all except ``Returns`` are
+applicable).  The constructor (``__init__``) should also be documented
+here, the **parameters** section of the docstring details the constructors
+parameters.
+
+An ``Attributes`` section, located below the **parameters** section,
+may be used to describe class variables::
+
+  Attributes
+  ----------
+  x : float
+      The X coordinate.
+  y : float
+      The Y coordinate.
+
+Attributes that are properties and have their own docstrings can be
+simply listed by name::
+
+  Attributes
+  ----------
+  real
+  imag
+  x : float
+      The X coordinate
+  y : float
+      The Y coordinate
+
+In general, it is not necessary to list class methods.  Those that are
+not part of the public API have names that start with an underscore.
+In some cases, however, a class may have a great many methods, of
+which only a few are relevant (e.g., subclasses of ndarray).  Then, it
+becomes useful to have an additional ``Methods`` section::
+
+  class Photo(ndarray):
+      """
+      Array with associated photographic information.
+
+      ...
+
+      Attributes
+      ----------
+      exposure : float
+          Exposure in seconds.
+
+      Methods
+      -------
+      colorspace(c='rgb')
+          Represent the photo in the given colorspace.
+      gamma(n=1.0)
+          Change the photo's gamma exposure.
+
+      """
+
+If it is necessary to explain a private method (use with care!), it can
+be referred to in the **extended summary** or the **notes**. Do not
+list private methods in the Methods section.
+
+Note that `self` is *not* listed as the first parameter of methods.
+
+Method docstrings
+`````````````````
+Document these as you would any other function.  Do not include
+``self`` in the list of parameters.
+
+Documenting class instances
+---------------------------
+Instances of classes that are part of the Numpy API (for example `np.r_`
+`np,c_`, `np.index_exp`, etc.) may require some care. To give these
+instances a useful docstring, we do the following:
+
+* Single instance: If only a single instance of a class is exposed,
+  document the class. Examples can use the instance name.
+
+* Multiple instances: If multiple instances are exposed, docstrings
+  for each instance are written and assigned to the instances'
+  ``__doc__`` attributes at run time. The class is documented as usual, and
+  the exposed instances can be mentioned in the Notes and See Also sections.
+
+Documenting constants
+---------------------
+Use the same sections as outlined for functions where applicable::
+
+   1. summary
+   2. extended summary (optional)
+   3. see also (optional)
+   4. references (optional)
+   5. examples (optional)
+
+Docstrings for constants will not be visible in text terminals
+(constants are of immutable type, so docstrings can not be assigned
+to them like for for class instances), but will appear in the
+documentation built with Sphinx.
+
+Other points to keep in mind
+----------------------------
+* Notes and Warnings : If there are points in the docstring that deserve
+  special emphasis, the reST directives for a note or warning can be used
+  in the vicinity of the context of the warning (inside a section). Syntax:
+
+  ::
+
+    .. warning:: Warning text.
+
+    .. note:: Note text.
+
+  Use these sparingly, as they do not look very good in text terminals
+  and are not often necessary. One situation in which a warning can
+  be useful is for marking a known bug that is not yet fixed.
+
+* Questions and Answers : For general questions on how to write docstrings
+  that are not answered in this document, refer to
+  `<http://docs.scipy.org/numpy/Questions+Answers/>`_.
+
+* array_like : For functions that take arguments which can have not only
+  a type `ndarray`, but also types that can be converted to an ndarray
+  (i.e. scalar types, sequence types), those arguments can be documented
+  with type `array_like`.
+
+Common reST concepts
+--------------------
+For paragraphs, indentation is significant and indicates indentation in the
+output. New paragraphs are marked with a blank line.
+
+Use *italics*, **bold**, and ``courier`` if needed in any explanations
+(but not for variable names and doctest code or multi-line code).
+Variable, module and class names should be written between single
+backticks (```numpy```).
+
+A more extensive example of reST markup can be found in `this example
+document <http://docutils.sourceforge.net/docs/user/rst/demo.txt>`_;
+the `quick reference
+<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ is
+useful while editing.
+
+Line spacing and indentation are significant and should be carefully
+followed.
+
+Conclusion
+----------
+
+`An example <http://github.com/numpy/numpy/blob/master/doc/example.py>`_ of the
+format shown here is available.  Refer to `How to Build API/Reference
+Documentation
+<http://github.com/numpy/numpy/blob/master/doc/HOWTO_BUILD_DOCS.txt>`_
+on how to use Sphinx_ to build the manual.
+
+This document itself was written in ReStructuredText, and may be converted to
+HTML using::
+
+  $ rst2html HOWTO_DOCUMENT.txt HOWTO_DOCUMENT.html
+
+.. _SciPy: http://www.scipy.org
+.. _numpy-discussion list: http://www.scipy.org/Mailing_Lists
+.. _Sphinx: http://sphinx.pocoo.org