From 11d67d46931887f4f4e05da080cf99414bff329d Mon Sep 17 00:00:00 2001 From: mattip Date: Wed, 16 Sep 2020 16:15:03 +0300 Subject: DOC, BLD: update doc build dependencies, remove as numpydoc submodule --- doc/source/docs/howto_document.rst | 26 ++------------------------ 1 file changed, 2 insertions(+), 24 deletions(-) (limited to 'doc/source/docs/howto_document.rst') diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst index cf86b7e99..9f9068ab3 100644 --- a/doc/source/docs/howto_document.rst +++ b/doc/source/docs/howto_document.rst @@ -40,29 +40,7 @@ after which you may use it:: np.fft.fft2(...) -.. rubric:: - **For convenience the** `formatting standard`_ **is included below with an - example** - -.. include:: ../../sphinxext/doc/format.rst - -.. _example: - -Example Source -============== - -.. literalinclude:: ../../sphinxext/doc/example.py - - - -Example Rendered -================ - -.. ifconfig:: python_version_major < '3' - - The example is rendered only when sphinx is run with python3 and above - -.. automodule:: doc.example - :members: +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 -- cgit v1.2.1 From 47c32b959ae71eb2c65c3b9b06796614105f5964 Mon Sep 17 00:00:00 2001 From: Ben Nathanson Date: Mon, 28 Sep 2020 15:55:23 -0400 Subject: DOC: Replace "About NumPy" with "Document conventions" Eliminates the unhelpful "About NumPy" title. All contents of the original appear more prominently elsewhere, except for the information about document conventions, which is now the title and subject. --- doc/source/docs/howto_document.rst | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc/source/docs/howto_document.rst') diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst index 9f9068ab3..5a36fa718 100644 --- a/doc/source/docs/howto_document.rst +++ b/doc/source/docs/howto_document.rst @@ -4,10 +4,15 @@ A Guide to NumPy/SciPy Documentation ==================================== +.. _userdoc_guide: + User documentation ******************* NumPy text documents should follow the `Google developer documentation style guide `_. + +.. _docstring_intro: + Docstrings ********** -- cgit v1.2.1 From d7b88ad4b695f7994f471d2f0b4e493d072d3cc1 Mon Sep 17 00:00:00 2001 From: Ben Nathanson Date: Mon, 28 Sep 2020 17:14:07 -0400 Subject: DOC: Update info on doc style rules --- doc/source/docs/howto_document.rst | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) (limited to 'doc/source/docs/howto_document.rst') diff --git a/doc/source/docs/howto_document.rst b/doc/source/docs/howto_document.rst index 9f9068ab3..7cd97b954 100644 --- a/doc/source/docs/howto_document.rst +++ b/doc/source/docs/howto_document.rst @@ -1,12 +1,36 @@ .. _howto-document: -A Guide to NumPy/SciPy Documentation -==================================== +A Guide to NumPy Documentation +============================== User documentation -******************* -NumPy text documents should follow the `Google developer documentation style guide `_. +****************** +- In general, we follow the + `Google developer documentation style 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 `_, + 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 + `_. + +- We welcome being + `alerted `_ to cases + we should add to the NumPy style rules. + Docstrings ********** -- cgit v1.2.1