[Numpy-svn] r5413 - branches/1.1.x/numpy/doc
numpy-svn at scipy.org
numpy-svn at scipy.org
Tue Jul 15 03:38:15 EDT 2008
Author: stefan
Date: 2008-07-15 02:38:00 -0500 (Tue, 15 Jul 2008)
New Revision: 5413
Added:
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.
Added: branches/1.1.x/numpy/doc/EXAMPLE_DOCSTRING.txt
===================================================================
--- 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
+ other functions, start with the one line description.
+
+
+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.
+
+See Also
+--------
+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
+"spread").
+
+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
-sphinx_ in their task.
+have written pre-processors to assist tools like epydoc_ and sphinx_ in
+their task.
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::
+
+ 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
@@ -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 @@
See Also
--------
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
-----
More information about the Numpy-svn
mailing list