diff options
Diffstat (limited to 'numpy')
| -rw-r--r-- | numpy/doc/HOWTO_BUILD_DOCS.txt | 11 | ||||
| -rw-r--r-- | numpy/doc/HOWTO_DOCUMENT.txt | 54 | ||||
| -rw-r--r-- | numpy/doc/example.py | 4 |
3 files changed, 56 insertions, 13 deletions
diff --git a/numpy/doc/HOWTO_BUILD_DOCS.txt b/numpy/doc/HOWTO_BUILD_DOCS.txt index b7acc2f11..9b1cca2f0 100644 --- a/numpy/doc/HOWTO_BUILD_DOCS.txt +++ b/numpy/doc/HOWTO_BUILD_DOCS.txt @@ -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 @@ Then, run epydoc:: 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 diff --git a/numpy/doc/HOWTO_DOCUMENT.txt b/numpy/doc/HOWTO_DOCUMENT.txt index a84260ac1..212cada3b 100644 --- a/numpy/doc/HOWTO_DOCUMENT.txt +++ b/numpy/doc/HOWTO_DOCUMENT.txt @@ -25,15 +25,24 @@ Use a code checker: * `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 @@ 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 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,10 +186,30 @@ The sections of the docstring are: 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** @@ -206,7 +235,7 @@ The sections of the docstring are: :: - 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 @@ Conclusion `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:: diff --git a/numpy/doc/example.py b/numpy/doc/example.py index d6b2fce80..152e2a622 100644 --- a/numpy/doc/example.py +++ b/numpy/doc/example.py @@ -80,7 +80,9 @@ def foo(var1, var2, long_var_name='hi') : 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 ----- |