# [Numpy-svn] r5413 - branches/1.1.x/numpy/doc

numpy-svn@scip... numpy-svn@scip...
Tue Jul 15 02:38:15 CDT 2008

Author: stefan
Date: 2008-07-15 02:38:00 -0500 (Tue, 15 Jul 2008)
New Revision: 5413

branches/1.1.x/numpy/doc/EXAMPLE_DOCSTRING.txt
Modified:
branches/1.1.x/numpy/doc/HOWTO_DOCUMENT.txt
branches/1.1.x/numpy/doc/example.py
Log:
Back-port changes to documentation standard.

===================================================================
--- branches/1.1.x/numpy/doc/EXAMPLE_DOCSTRING.txt	2008-07-15 07:06:38 UTC (rev 5412)
+++ branches/1.1.x/numpy/doc/EXAMPLE_DOCSTRING.txt	2008-07-15 07:38:00 UTC (rev 5413)
@@ -0,0 +1,104 @@
+.. Here follows an example docstring for a C-function.  Note that the
+   signature is given.  This is done only for functions written is C,
+   since Python cannot find their signature by inspection.  For all
+
+
+multivariate_normal(mean, cov[, shape])
+
+Draw samples from a multivariate normal distribution.
+
+The multivariate normal, multinormal or Gaussian distribution is a
+generalisation of the one-dimensional normal distribution to higher
+dimensions.
+
+Such a distribution is specified by its mean and covariance matrix,
+which are analogous to the mean (average or "centre") and variance
+(standard deviation squared or "width") of the one-dimensional normal
+distribution.
+
+Parameters
+----------
+mean : (N,) ndarray
+    Mean of the N-dimensional distribution.
+cov : (N,N) ndarray
+    Covariance matrix of the distribution.
+shape : tuple of ints, optional
+    Given a shape of, for example, (m,n,k), m*n*k samples are
+    generated, and packed in an m-by-n-by-k arrangement.  Because each
+    sample is N-dimensional, the output shape is (m,n,k,N).  If no
+    shape is specified, a single sample is returned.
+
+Returns
+-------
+out : ndarray
+    The drawn samples, arranged according to shape.  If the
+    shape given is (m,n,...), then the shape of out is is
+    (m,n,...,N).
+
+    In other words, each entry out[i,j,...,:] is an N-dimensional
+    value drawn from the distribution.
+
+--------
+normal
+scipy.stats.distributions.norm : Provides random variates, as well as
+                                 probability density function, cumulative
+                                 density function, etc.
+
+Notes
+-----
+The mean is a coordinate in N-dimensional space, which represents the
+location where samples are most likely to be generated.  This is
+analogous to the peak of the bell curve for the one-dimensional or
+univariate normal distribution.
+
+Covariance indicates the level to which two variables vary together.
+From the multivariate normal distribution, we draw N-dimensional
+samples, :math:X = [x_1, x_2, ... x_N].  The covariance matrix
+element :math:C_ij is the covariance of :math:x_i and :math:x_j.
+The element :math:C_ii is the variance of :math:x_i (i.e. its
+
+Instead of specifying the full covariance matrix, popular
+approximations include:
+
+  - Spherical covariance (cov is a multiple of the identity matrix)
+  - Diagonal covariance (cov has non-negative elements, and only on
+    the diagonal)
+
+This geometrical property can be seen in two dimensions by plotting
+generated data-points:
+
+>>> mean = [0,0]
+>>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis
+>>> x,y = np.random.multivariate_normal(mean,cov,5000).T
+
+>>> import matplotlib.pyplot as plt
+>>> plt.plot(x,y,'x'); plt.axis('equal'); pyplot.show()
+
+Note that the covariance matrix must be non-negative definite.
+
+References
+----------
+.. [1] A. Papoulis, "Probability, Random Variables, and Stochastic
+       Processes," 3rd ed., McGraw-Hill Companies, 1991
+.. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification,"
+       2nd ed., Wiley, 2001.
+
+Examples
+--------
+>>> mean = (1,2)
+>>> cov = [[1,0],[1,0]]
+>>> x = np.random.multivariate_normal(mean,cov,(3,3))
+>>> x.shape
+(3, 3, 2)
+
+The following is probably true, given that 0.6 is roughly twice the
+standard deviation:
+
+>>> print list( (x[0,0,:] - mean) < 0.6 )
+[True, True]
+
+.. index:
+   :refguide: random:distributions

Modified: branches/1.1.x/numpy/doc/HOWTO_DOCUMENT.txt
===================================================================
--- branches/1.1.x/numpy/doc/HOWTO_DOCUMENT.txt	2008-07-15 07:06:38 UTC (rev 5412)
+++ branches/1.1.x/numpy/doc/HOWTO_DOCUMENT.txt	2008-07-15 07:38:00 UTC (rev 5413)
@@ -25,15 +25,24 @@
* pyflakes easy_install pyflakes
* pep8.py <http://svn.browsershots.org/trunk/devtools/pep8/pep8.py>_

-For documentation purposes, use unabbreviated module names.  If you
-prefer the use of abbreviated module names in code (*not* the
-docstrings), we suggest the import conventions used by NumPy itself::
+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,
@@ -65,15 +74,15 @@
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 chosen to write pre-processors to assist tools like epydoc_ or
+have written pre-processors to assist tools like epydoc_ and sphinx_ in

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 wiki-based documentation system (see the Developer Zone
+our new documentation system (see the Developer Zone
<http://www.scipy.org/Developer_Zone/DocMarathon2008>_).

Sections
@@ -179,6 +188,29 @@
--------
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::
+
+     --------
+     func_a : Function a with its description.
+     func_b, func_c_, func_d
+     func_e
+
8. **Notes**

@@ -203,8 +235,14 @@

::

-     The value of :math:omega is larger than 5.
+     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.

@@ -277,6 +315,11 @@
<BLANKLINE>
b

+    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.
+
11. **Indexing tags***

Each function needs to be categorised for indexing purposes.  Use
@@ -286,17 +329,67 @@
:refguide: ufunc, trigonometry

To index a function as a sub-category of a class, separate index
-    entries by a semi-colon, e.g.
+    entries by a colon, e.g.

::

-      :refguide: ufunc, numpy;reshape, other
+      :refguide: ufunc, numpy:reshape, other

A list of available categories
<http://www.scipy.org/Developer_Zone/ReferenceGuide>_ is
available.

+Documenting classes
+-------------------

+Class docstring
+
+Use the same sections as outlined above (all except Returns are
+applicable).  The constructor (__init__) should also be documented
+here.
+
+An Attributes section may be used to describe class variables::
+
+  Attributes
+  ----------
+  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.
+
+      """
+
+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.
+
Common reST concepts
--------------------
For paragraphs, indentation is significant and indicates indentation in the
@@ -322,8 +415,9 @@
An example
<http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py>_ of the
format shown here is available.  Refer to How to Build API/Reference
-Documentation <HOWTO_BUILD_DOCS>_ on how to use epydoc_ or sphinx_ to
-construct a manual and web page.
+Documentation
+<http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_BUILD_DOCS.txt>_
+on how to use epydoc_ or sphinx_ to construct a manual and web page.

This document itself was written in ReStructuredText, and may be converted to
HTML using::

Modified: branches/1.1.x/numpy/doc/example.py
===================================================================
--- branches/1.1.x/numpy/doc/example.py	2008-07-15 07:06:38 UTC (rev 5412)
+++ branches/1.1.x/numpy/doc/example.py	2008-07-15 07:38:00 UTC (rev 5413)
@@ -80,7 +80,9 @@
--------
otherfunc : relationship (optional)
-    newfunc : relationship (optional)
+    newfunc : Relationship (optional), which could be fairly long, in which
+              case the line wraps here.
+    thirdfunc, fourthfunc, fifthfunc

Notes
-----