[Numpy-svn] r5247 - trunk/numpy/doc

[numpy-svn at scipy.org]

Author: stefan
Date: 2008-06-03 03:50:08 -0500 (Tue, 03 Jun 2008)
New Revision: 5247

Modified:
   trunk/numpy/doc/HOWTO_BUILD_DOCS.txt
   trunk/numpy/doc/HOWTO_DOCUMENT.txt
   trunk/numpy/doc/example.py
Log:
Update documentation standard.


Modified: trunk/numpy/doc/HOWTO_BUILD_DOCS.txt
===================================================================
--- trunk/numpy/doc/HOWTO_BUILD_DOCS.txt	2008-06-01 00:53:50 UTC (rev 5246)
+++ trunk/numpy/doc/HOWTO_BUILD_DOCS.txt	2008-06-03 08:50:08 UTC (rev 5247)
@@ -2,6 +2,12 @@
 Building the NumPy API and reference docs
 =========================================
 
+Using Sphinx_
+-------------
+`Download <https://code.launchpad.net/~stefanv/scipy/numpy-refguide>`_
+the builder.  Follow the instructions in ``README.txt``.
+
+
 Using Epydoc_
 -------------
 
@@ -58,3 +64,8 @@
 
 The output is placed in ``./html``, and may be viewed by loading the
 ``index.html`` file into your browser.
+
+
+
+.. _epydoc: http://epydoc.sourceforge.net/
+.. _sphinx: http://sphinx.pocoo.org

Modified: trunk/numpy/doc/HOWTO_DOCUMENT.txt
===================================================================
--- trunk/numpy/doc/HOWTO_DOCUMENT.txt	2008-06-01 00:53:50 UTC (rev 5246)
+++ trunk/numpy/doc/HOWTO_DOCUMENT.txt	2008-06-03 08:50:08 UTC (rev 5247)
@@ -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,8 +74,8 @@
 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
 ------
@@ -177,11 +186,31 @@
 
      See Also
      --------
-     numpy.average : Weighted average
-   
-   Preferably, use the full namespace prefixes. For targets in the same
-   module as the documented object, the prefix can be omitted.
+     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
@@ -206,7 +235,7 @@
 
    ::
 
-     The value of :math:`omega` is larger than 5.
+     The value of :math:`\omega` is larger than 5.
 
    Note that LaTeX is not particularly easy to read, so use equations
    sparingly.
@@ -329,8 +358,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: trunk/numpy/doc/example.py
===================================================================
--- trunk/numpy/doc/example.py	2008-06-01 00:53:50 UTC (rev 5246)
+++ trunk/numpy/doc/example.py	2008-06-03 08:50:08 UTC (rev 5247)
@@ -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
     -----