diff options
| -rw-r--r-- | doc/HOWTO_DOCUMENT.rst.txt | 20 |
1 files changed, 20 insertions, 0 deletions
diff --git a/doc/HOWTO_DOCUMENT.rst.txt b/doc/HOWTO_DOCUMENT.rst.txt index 61d7c3941..eeeb50711 100644 --- a/doc/HOWTO_DOCUMENT.rst.txt +++ b/doc/HOWTO_DOCUMENT.rst.txt @@ -9,6 +9,26 @@ A Guide to NumPy/SciPy Documentation For an accompanying example, see `example.py <http://github.com/numpy/numpy/blob/master/doc/example.py>`_. + When using `Sphinx <http://sphinx.pocoo.org/>`_ in combination with the numpy + conventions, you may be interested in the ``numpydoc`` extension, which will + handle your docstrings correctly. For example, it will extract the + ``Parameters`` section from your docstring and convert this into a field list. + It can also help alleviate reStructuredText errors encounterde when using + plain sphinx. Sphinx gets confused because the numpy docstrings have section + headers (e.g. ``-------------``) which sphinx does not expect to find in + docstrings. + + It is available from: + + * `numpydoc on PyPI <http://pypi.python.org/pypi/numpydoc>`_ + * `numpydoc on GitHub (in main numpy repository) + <https://github.com/numpy/numpy/blob/master/doc/sphinxext/numpydoc.py>`_ + + Details of how to use it can be found `here + <https://github.com/numpy/numpy/blob/master/doc/sphinxext/README.txt>`_ and + `here + <https://github.com/numpy/numpy/blob/master/doc/HOWTO_BUILD_DOCS.rst.txt>`_ + Overview -------- In general, we follow the standard Python style conventions as described here: |