From 9c833cdd224177e86f98488cef0478ea0d5397a0 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 15 Jun 2020 00:30:31 -0700 Subject: [PATCH 1/8] updated doc guide with "documenting changes" Taken from https://github.com/MDAnalysis/mdanalysis/wiki/WritingDocumentation#documenting-changes in response to https://github.com/MDAnalysis/mdanalysis/pull/2754#discussion_r439862254 --- doc/source/contributing_code.rst | 38 ++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index 6289de844..62bb2b000 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -699,6 +699,44 @@ A typical function docstring looks like the following: See `Stackoverflow: Mathjax expression in sphinx python not rendering correctly `_ for further discussion. + +------------------- +Documenting changes +------------------- + +.. _versionadded: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded +.. _versionchanged: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionchanged +.. _deprecated: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated + +We use reST constructs to annotate *additions*, *changes*, *deprecations* to the code so that users can quickly learn from the documentation in which version of MDAnalysis the feature is available. + +A **newly added module/class/method/attribute/function** gets a `versionadded`_ directive + +.. code-block:: rst + + .. versionadded:: X.Y.Z + +entry in its primary doc section. For parameters and attributes, we typically mention the new entity in a `versionchanged`_ section of the function or class (although a `versionadded`_ would also be acceptable). + +**Changes** are indicated with a `versionchanged`_ directive + +.. code-block:: rst + .. versionchanged:: X.Y.Z + Description of the change. Can contain multiple descriptions. + Don't assume that you get nice line breaks or formatting, write your text in + full sentences that can be read as a paragraph. + +**Deprecations** (features that are not any longer recommended for use and that will be removed in future releases) are indicated by the `deprecated`_ directive + +.. code-block:: rst + .. deprecated:: X.Y.Z + Describe (1) alternatives (what should users rather use) and + (2) in which future release the feature will be removed. + +When a feature is removed, we remove the deprecation notice and add a `versionchanged`_ to the docs of the enclosing scope. E.g., when a parameter of a function is removed, we update the docs of the function. Function/class removal are indicated in the module docs. When we remove a whole module, we typically indicate it in the top-level reST docs that contain the TOC tree that included the module. + + + -------------------------------------- Writing docs for abstract base classes -------------------------------------- From 7f76974ee669c4d1eb932fba3c051b822cfe2ab7 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 15 Jun 2020 09:36:01 -0700 Subject: [PATCH 2/8] Update doc/source/contributing_code.rst Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- doc/source/contributing_code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index 62bb2b000..fbc207a6d 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -710,7 +710,7 @@ Documenting changes We use reST constructs to annotate *additions*, *changes*, *deprecations* to the code so that users can quickly learn from the documentation in which version of MDAnalysis the feature is available. -A **newly added module/class/method/attribute/function** gets a `versionadded`_ directive +A **newly added module/class/method/attribute/function** gets a `versionadded`_ directive entry in its primary doc section, as below. .. code-block:: rst From 2437feec6d28b00b3b0b38dada77a6f8dfa720f5 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 15 Jun 2020 09:36:16 -0700 Subject: [PATCH 3/8] Update doc/source/contributing_code.rst Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- doc/source/contributing_code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index fbc207a6d..aa7ae97a3 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -708,7 +708,7 @@ Documenting changes .. _versionchanged: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionchanged .. _deprecated: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated -We use reST constructs to annotate *additions*, *changes*, *deprecations* to the code so that users can quickly learn from the documentation in which version of MDAnalysis the feature is available. +We use reST constructs to annotate *additions*, *changes*, and *deprecations* to the code so that users can quickly learn from the documentation in which version of MDAnalysis the feature is available. A **newly added module/class/method/attribute/function** gets a `versionadded`_ directive entry in its primary doc section, as below. From da479eca354613ccc602a1d7ea81f476e1a290d3 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 15 Jun 2020 09:36:49 -0700 Subject: [PATCH 4/8] Update doc/source/contributing_code.rst Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- doc/source/contributing_code.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index aa7ae97a3..f029da2a2 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -721,6 +721,7 @@ entry in its primary doc section. For parameters and attributes, we typically me **Changes** are indicated with a `versionchanged`_ directive .. code-block:: rst + .. versionchanged:: X.Y.Z Description of the change. Can contain multiple descriptions. Don't assume that you get nice line breaks or formatting, write your text in From 753afa1425e0fa437d1f8b44f980a16a7bd335b6 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 15 Jun 2020 09:36:55 -0700 Subject: [PATCH 5/8] Update doc/source/contributing_code.rst Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- doc/source/contributing_code.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index f029da2a2..1ea66435a 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -730,6 +730,7 @@ entry in its primary doc section. For parameters and attributes, we typically me **Deprecations** (features that are not any longer recommended for use and that will be removed in future releases) are indicated by the `deprecated`_ directive .. code-block:: rst + .. deprecated:: X.Y.Z Describe (1) alternatives (what should users rather use) and (2) in which future release the feature will be removed. From 7ec9f57489cba6a8d7b308ac64d4d1bae6743739 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 15 Jun 2020 09:37:13 -0700 Subject: [PATCH 6/8] Update doc/source/contributing_code.rst Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- doc/source/contributing_code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index 1ea66435a..e8b8a1743 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -735,7 +735,7 @@ entry in its primary doc section. For parameters and attributes, we typically me Describe (1) alternatives (what should users rather use) and (2) in which future release the feature will be removed. -When a feature is removed, we remove the deprecation notice and add a `versionchanged`_ to the docs of the enclosing scope. E.g., when a parameter of a function is removed, we update the docs of the function. Function/class removal are indicated in the module docs. When we remove a whole module, we typically indicate it in the top-level reST docs that contain the TOC tree that included the module. +When a feature is removed, we remove the deprecation notice and add a `versionchanged`_ to the docs of the enclosing scope. For example, when a parameter of a function is removed, we update the docs of the function. Function/class removal are indicated in the module docs. When we remove a whole module, we typically indicate it in the top-level reST docs that contain the TOC tree that originally included the module. From 7425ba06c9ff5b42181b17f9cbd177eb4bae73e7 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 15 Jun 2020 09:37:30 -0700 Subject: [PATCH 7/8] Update doc/source/contributing_code.rst Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- doc/source/contributing_code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index e8b8a1743..b3a52cb62 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -727,7 +727,7 @@ entry in its primary doc section. For parameters and attributes, we typically me Don't assume that you get nice line breaks or formatting, write your text in full sentences that can be read as a paragraph. -**Deprecations** (features that are not any longer recommended for use and that will be removed in future releases) are indicated by the `deprecated`_ directive +**Deprecations** (features that are not any longer recommended for use and that will be removed in future releases) are indicated by the `deprecated`_ directive: .. code-block:: rst From 26cde8f310ba21804f5bdaca74d17bdc76548027 Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 15 Jun 2020 09:37:55 -0700 Subject: [PATCH 8/8] Update doc/source/contributing_code.rst Co-authored-by: Lily Wang <31115101+lilyminium@users.noreply.github.com> --- doc/source/contributing_code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/contributing_code.rst b/doc/source/contributing_code.rst index b3a52cb62..7c63450d4 100644 --- a/doc/source/contributing_code.rst +++ b/doc/source/contributing_code.rst @@ -716,7 +716,7 @@ A **newly added module/class/method/attribute/function** gets a `versionadded`_ .. versionadded:: X.Y.Z -entry in its primary doc section. For parameters and attributes, we typically mention the new entity in a `versionchanged`_ section of the function or class (although a `versionadded`_ would also be acceptable). +For parameters and attributes, we typically mention the new entity in a `versionchanged`_ section of the function or class (although a `versionadded`_ would also be acceptable). **Changes** are indicated with a `versionchanged`_ directive