diff options
| -rw-r--r-- | doc/source/_templates/indexcontent.html | 7 | ||||
| -rw-r--r-- | doc/source/conf.py | 1 | ||||
| -rw-r--r-- | doc/source/dev/howto-docs.rst | 63 | ||||
| -rw-r--r-- | doc/source/dev/howto_build_docs.rst (renamed from doc/source/docs/howto_build_docs.rst) | 0 | ||||
| -rw-r--r-- | doc/source/dev/index.rst | 1 | ||||
| -rw-r--r-- | doc/source/doc_conventions.rst | 23 | ||||
| -rw-r--r-- | doc/source/docs/howto_document.rst | 75 | ||||
| -rw-r--r-- | doc/source/docs/index.rst | 11 | ||||
| -rw-r--r-- | doc/source/user/absolute_beginners.rst | 7 | ||||
| -rw-r--r-- | doc/source/user/index.rst | 2 |
10 files changed, 73 insertions, 117 deletions
diff --git a/doc/source/_templates/indexcontent.html b/doc/source/_templates/indexcontent.html index 4cbe7d4d5..450cb1e2e 100644 --- a/doc/source/_templates/indexcontent.html +++ b/doc/source/_templates/indexcontent.html @@ -41,8 +41,8 @@ <span class="linkdescr">Contributing to NumPy</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("dev/underthehood") }}">Under-the-hood docs</a><br/> <span class="linkdescr">Specialized, in-depth documentation</span></p> - <p class="biglink"><a class="biglink" href="{{ pathto("docs/howto_document") }}">A guide to NumPy documentation</a><br/> - <p class="biglink"><a class="biglink" href="{{ pathto("docs/howto_build_docs") }}">Building the NumPy API and reference docs</a><br/> + <p class="biglink"><a class="biglink" href="{{ pathto("dev/howto-docs") }}">How to contribute to the NumPy documentation</a><br/> + <p class="biglink"><a class="biglink" href="{{ pathto("dev/howto_build_docs") }}">Building the NumPy API and reference docs</a><br/> <p class="biglink"><a class="biglink" href="{{ pathto("benchmarking") }}">Benchmarking</a><br/> <span class="linkdescr">benchmarking NumPy</span></p> <p class="biglink"><a class="biglink" href="https://www.numpy.org/neps/index.html">NumPy Enhancement Proposals</a><br/> @@ -55,7 +55,6 @@ <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">Reporting bugs</a></p> <p class="biglink"><a class="biglink" href="{{ pathto("release") }}">Release notes</a></p> </td><td width="50%"> - <p class="biglink"><a class="biglink" href="{{ pathto("doc_conventions") }}">Document conventions</a></p> <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">License of NumPy</a></p> </td></tr> </table> @@ -70,7 +69,7 @@ </p> <p> The preferred way to update the documentation is by submitting a pull - request on GitHub (see the <a href="{{ pathto("docs/index") }}">Documentation index</a>). + request on GitHub (see the <a href="{{ pathto("dev/howto-docs") }}">Documentation guide</a>). Please help us to further improve the NumPy documentation! </p> {% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py index 587307cf9..41b5cee25 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -300,6 +300,7 @@ intersphinx_mapping = { 'scipy-lecture-notes': ('https://scipy-lectures.org', None), 'pytest': ('https://docs.pytest.org/en/stable', None), 'numpy-tutorials': ('https://numpy.org/numpy-tutorials', None), + 'numpydoc': ('https://numpydoc.readthedocs.io/en/latest', None), } diff --git a/doc/source/dev/howto-docs.rst b/doc/source/dev/howto-docs.rst index 9354357e8..3156d3452 100644 --- a/doc/source/dev/howto-docs.rst +++ b/doc/source/dev/howto-docs.rst @@ -153,6 +153,69 @@ if you write a tutorial on your blog, create a YouTube video, or answer question on Stack Overflow and other sites. +.. _howto-document: + +******************* +Documentation style +******************* + +.. _userdoc_guide: + +User documentation +================== + +- In general, we follow the + `Google developer documentation style guide <https://developers.google.com/style>`_ + for the User Guide. + +- NumPy style governs cases where: + + - Google has no guidance, or + - We prefer not to use the Google style + + Our current rules: + + - We pluralize *index* as *indices* rather than + `indexes <https://developers.google.com/style/word-list#letter-i>`_, + following the precedent of :func:`numpy.indices`. + + - For consistency we also pluralize *matrix* as *matrices*. + +- Grammatical issues inadequately addressed by the NumPy or Google rules are + decided by the section on "Grammar and Usage" in the most recent edition of + the `Chicago Manual of Style + <https://en.wikipedia.org/wiki/The_Chicago_Manual_of_Style>`_. + +- We welcome being + `alerted <https://github.com/numpy/numpy/issues>`_ to cases + we should add to the NumPy style rules. + +.. _docstring_intro: + +Docstrings +========== + +When using `Sphinx <http://www.sphinx-doc.org/>`_ in combination with the +NumPy conventions, you should use the ``numpydoc`` extension so that your +docstrings will be handled correctly. For example, Sphinx will extract the +``Parameters`` section from your docstring and convert it into a field +list. Using ``numpydoc`` will also avoid the reStructuredText errors produced +by plain Sphinx when it encounters NumPy docstring conventions like +section headers (e.g. ``-------------``) that sphinx does not expect to +find in docstrings. + +It is available from: + +* `numpydoc on PyPI <https://pypi.python.org/pypi/numpydoc>`_ +* `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_ + +Note that for documentation within NumPy, it is not necessary to do +``import numpy as np`` at the beginning of an example. + +Please use the ``numpydoc`` :ref:`formatting standard <numpydoc:format>` as +shown in their :ref:`example <numpydoc:example>`. + + ********************* Documentation reading ********************* diff --git a/doc/source/docs/howto_build_docs.rst b/doc/source/dev/howto_build_docs.rst index 884cf7935..884cf7935 100644 --- a/doc/source/docs/howto_build_docs.rst +++ b/doc/source/dev/howto_build_docs.rst diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst index b9347a58c..a8c969267 100644 --- a/doc/source/dev/index.rst +++ b/doc/source/dev/index.rst @@ -257,6 +257,7 @@ The rest of the story Git Basics <gitwash/index> development_environment development_gitpod + howto_build_docs development_workflow development_advanced_debugging reviewer_guidelines diff --git a/doc/source/doc_conventions.rst b/doc/source/doc_conventions.rst deleted file mode 100644 index e2bc419d1..000000000 --- a/doc/source/doc_conventions.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _documentation_conventions: - -############################################################################## -Documentation conventions -############################################################################## - -- Names that look like :func:`numpy.array` are links to detailed - documentation. - -- Examples often include the Python prompt ``>>>``. This is not part of the - code and will cause an error if typed or pasted into the Python - shell. It can be safely typed or pasted into the IPython shell; the ``>>>`` - is ignored. - -- Examples often use ``np`` as an alias for ``numpy``; that is, they assume - you've run:: - - >>> import numpy as np - -- If you're a code contributor writing a docstring, see :ref:`docstring_intro`. - -- If you're a writer contributing ordinary (non-docstring) documentation, see - :ref:`userdoc_guide`. diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst deleted file mode 100644 index ff726c67c..000000000 --- a/doc/source/docs/howto_document.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _howto-document: - - -A Guide to NumPy Documentation -============================== - -.. _userdoc_guide: - -User documentation -****************** -- In general, we follow the - `Google developer documentation style guide <https://developers.google.com/style>`_. - -- NumPy style governs cases where: - - - Google has no guidance, or - - We prefer not to use the Google style - - Our current rules: - - - We pluralize *index* as *indices* rather than - `indexes <https://developers.google.com/style/word-list#letter-i>`_, - following the precedent of :func:`numpy.indices`. - - - For consistency we also pluralize *matrix* as *matrices*. - -- Grammatical issues inadequately addressed by the NumPy or Google rules are - decided by the section on "Grammar and Usage" in the most recent edition of - the `Chicago Manual of Style - <https://en.wikipedia.org/wiki/The_Chicago_Manual_of_Style>`_. - -- We welcome being - `alerted <https://github.com/numpy/numpy/issues>`_ to cases - we should add to the NumPy style rules. - - - -.. _docstring_intro: - -Docstrings -********** - -When using `Sphinx <http://www.sphinx-doc.org/>`__ in combination with the -numpy conventions, you should use the ``numpydoc`` extension so that your -docstrings will be handled correctly. For example, Sphinx will extract the -``Parameters`` section from your docstring and convert it into a field -list. Using ``numpydoc`` will also avoid the reStructuredText errors produced -by plain Sphinx when it encounters numpy docstring conventions like -section headers (e.g. ``-------------``) that sphinx does not expect to -find in docstrings. - -Some features described in this document require a recent version of -``numpydoc``. For example, the **Yields** section was added in -``numpydoc`` 0.6. - -It is available from: - -* `numpydoc on PyPI <https://pypi.python.org/pypi/numpydoc>`_ -* `numpydoc on GitHub <https://github.com/numpy/numpydoc/>`_ - -Note that for documentation within numpy, 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(...) - -Please use the numpydoc `formatting standard`_ as shown in their example_ - -.. _`formatting standard`: https://numpydoc.readthedocs.io/en/latest/format.html -.. _example: https://numpydoc.readthedocs.io/en/latest/example.html diff --git a/doc/source/docs/index.rst b/doc/source/docs/index.rst deleted file mode 100644 index 7d8b1bcb4..000000000 --- a/doc/source/docs/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _documentation: - -NumPy's Documentation -===================== - -.. toctree:: - :maxdepth: 2 - - howto_document - howto_build_docs - diff --git a/doc/source/user/absolute_beginners.rst b/doc/source/user/absolute_beginners.rst index 499e9ec5c..bb570f622 100644 --- a/doc/source/user/absolute_beginners.rst +++ b/doc/source/user/absolute_beginners.rst @@ -83,9 +83,12 @@ If you aren't familiar with this style, it's very easy to understand. If you see ``>>>``, you're looking at **input**, or the code that you would enter. Everything that doesn't have ``>>>`` in front of it is **output**, or the results of running your code. This is the style -you see when you run ``python`` on the command line, but if you're using IPython, you might see a different style. +you see when you run ``python`` on the command line, but if you're using +IPython, you might see a different style. Note that it is not part of the +code and will cause an error if typed or pasted into the Python +shell. It can be safely typed or pasted into the IPython shell; the ``>>>`` +is ignored. -For more information, see :ref:`documentation_conventions`. What’s the difference between a Python list and a NumPy array? -------------------------------------------------------------- diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index b3ecc3a95..e5c51351e 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -38,8 +38,6 @@ details are found in :ref:`reference`. ../f2py/index ../glossary ../dev/underthehood - ../docs/index ../bugs ../release - ../doc_conventions ../license |