From 13d4678c0ab37917843a5752910c74e54304a395 Mon Sep 17 00:00:00 2001 From: Matt Haberland Date: Thu, 21 Dec 2023 12:14:19 -0500 Subject: [PATCH 1/5] doc/format.rst --- doc/format.rst | 53 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index 2f9753c5..28daf036 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -175,8 +175,9 @@ respective types. y Description of parameter `y` (with type not specified). -Enclose variables in single backticks. The colon must be preceded -by a space, or omitted if the type is absent. +The colon must be preceded by a space, or omitted if the type is absent. +When referring to a parameter in the description field or elsewhere within +the same function or class docstring, enclose its name in single backticks. For the parameter types, be as precise as possible. Below are a few examples of parameters and their types. @@ -549,6 +550,8 @@ not explicitly imported, `.. plot::` can be used directly if Documenting classes ------------------- +.. _classdoc: + Class docstring ``````````````` Use the same sections as outlined above (all except :ref:`Returns ` @@ -562,10 +565,12 @@ section, may be used to describe non-method attributes of the class:: Attributes ---------- x : float - The X coordinate. + Description of attribute `x`. y : float - The Y coordinate. + Description of attribute `y`. +When referring to an attribute in the description field or elsewhere within +the same class docstring, enclose its name in single backticks. Attributes that are properties and have their own docstrings can be simply listed by name:: @@ -606,6 +611,8 @@ becomes useful to have an additional **Methods** section: """ +When referring to a method in the description field or elsewhere within +the same class docstring, enclose its name in single backticks. If it is necessary to explain a private method (use with care!), it can be referred to in the :ref:`Extended Summary ` or the :ref:`Notes ` section. @@ -690,11 +697,13 @@ belong in docstrings. Other points to keep in mind ---------------------------- * Equations : as discussed in the :ref:`Notes ` section above, LaTeX - formatting should be kept to a minimum. Often it's possible to show equations as - Python code or pseudo-code instead, which is much more readable in a - terminal. For inline display use double backticks (like ``y = np.sin(x)``). - For display with blank lines above and below, use a double colon and indent - the code, like:: + formatting should be kept to a minimum. Often it's possible to show + equations as Python code or pseudo-code instead, which is much more readable + in a terminal. For inline display of code (other than individual + :ref:`Parameters `, :ref:`class members `, and linked + modules,functions, and classes; see "Links" below), use double backticks, + like ````y = np.sin(x)````. For display with blank lines above and below, + use a double colon and indent the code, like:: end of previous sentence:: @@ -717,7 +726,9 @@ Other points to keep in mind (i.e. scalar types, sequence types), those arguments can be documented with type `array_like`. -* Links : If you need to include hyperlinks in your docstring, note that +* Links : Sphinx will automatically create hyperlinks to module, function, + and class documentation if a recognized name is included within single + backticks (e.g. `numpy`). If you need to include other hyperlinks, note that some docstring sections are not parsed as standard reST, and in these sections, numpydoc may become confused by hyperlink targets such as:: @@ -729,17 +740,27 @@ Other points to keep in mind `Example `_ - Common reST concepts -------------------- For paragraphs, indentation is significant and indicates indentation in the output. New paragraphs are marked with a blank line. -Use ``*italics*``, ``**bold**`` and ````monospace```` if needed in any -explanations -(but not for variable names and doctest code or multi-line code). -Variable, module, function, and class names should be written between -single back-ticks (```numpy```). +Use ``*italics*``, ``**bold**`` if needed in any explanations. + +Use of backticks in reST is a common point of confusion it is different from +markdown: + +- Module, function, and class names should be enclosed within ```single + backticks```. These are intended to render as hyperlinks (e.g. `numpy`). If + the hyperlinks do not render as intended, [insert reference to documentation + here]. +- References to parameters, attributes, and methods defined within the same + docstring should be enclosed within ```single backticks```. These are + currently rendered in *italics*, but there are plans to render a + ``monospaced`` hyperlink to the relevant definition in a future version of + numpydoc. +- All other text that is intended to render in ``monospaced`` font should be + enclosed within ````double backticks````. A more extensive example of reST markup can be found in `this example document `_; From 4895a4b405cfcab271b952d6485ceb5a9dfe86a9 Mon Sep 17 00:00:00 2001 From: Jarrod Millman Date: Mon, 5 Feb 2024 12:02:41 -0800 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Ross Barnowski Co-authored-by: Matt Haberland --- doc/format.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index 28daf036..e9048e44 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -699,9 +699,7 @@ Other points to keep in mind * Equations : as discussed in the :ref:`Notes ` section above, LaTeX formatting should be kept to a minimum. Often it's possible to show equations as Python code or pseudo-code instead, which is much more readable - in a terminal. For inline display of code (other than individual - :ref:`Parameters `, :ref:`class members `, and linked - modules,functions, and classes; see "Links" below), use double backticks, + in a terminal. For inline display of code use double backticks, like ````y = np.sin(x)````. For display with blank lines above and below, use a double colon and indent the code, like:: @@ -747,8 +745,8 @@ output. New paragraphs are marked with a blank line. Use ``*italics*``, ``**bold**`` if needed in any explanations. -Use of backticks in reST is a common point of confusion it is different from -markdown: +Use of backticks in reST is a common point of confusion because it is different +from markdown: - Module, function, and class names should be enclosed within ```single backticks```. These are intended to render as hyperlinks (e.g. `numpy`). If From f4bb0f2f8965442f874886483b29a057e0e8b436 Mon Sep 17 00:00:00 2001 From: Matt Haberland Date: Mon, 3 Jun 2024 07:45:23 -0700 Subject: [PATCH 3/5] MAINT: partially respond to some comments to prepare for discussion --- doc/format.rst | 43 ++++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index 28daf036..274f976e 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -176,8 +176,8 @@ respective types. Description of parameter `y` (with type not specified). The colon must be preceded by a space, or omitted if the type is absent. -When referring to a parameter in the description field or elsewhere within -the same function or class docstring, enclose its name in single backticks. +When referring to a parameter anywhere within the docstring, enclose its +name in single backticks. For the parameter types, be as precise as possible. Below are a few examples of parameters and their types. @@ -569,8 +569,8 @@ section, may be used to describe non-method attributes of the class:: y : float Description of attribute `y`. -When referring to an attribute in the description field or elsewhere within -the same class docstring, enclose its name in single backticks. +When referring to an attribute anywhere within the docstring, enclose its +name in single backticks. Attributes that are properties and have their own docstrings can be simply listed by name:: @@ -611,8 +611,8 @@ becomes useful to have an additional **Methods** section: """ -When referring to a method in the description field or elsewhere within -the same class docstring, enclose its name in single backticks. +When referring to a method anywhere within the docstring, enclose its +name in single backticks. If it is necessary to explain a private method (use with care!), it can be referred to in the :ref:`Extended Summary ` or the :ref:`Notes ` section. @@ -728,9 +728,10 @@ Other points to keep in mind * Links : Sphinx will automatically create hyperlinks to module, function, and class documentation if a recognized name is included within single - backticks (e.g. `numpy`). If you need to include other hyperlinks, note that - some docstring sections are not parsed as standard reST, and in these - sections, numpydoc may become confused by hyperlink targets such as:: + backticks (e.g. ```numpy``` renders as `numpy`). If you need to include + other hyperlinks, note that some docstring sections are not parsed as + standard reST, and in these sections, numpydoc may become confused by + hyperlink targets such as:: .. _Example: http://www.example.com @@ -747,18 +748,22 @@ output. New paragraphs are marked with a blank line. Use ``*italics*``, ``**bold**`` if needed in any explanations. -Use of backticks in reST is a common point of confusion it is different from -markdown: +Use of backticks in reST is a common point of confusion because it is different +from markdown. In most flavors of markdown, single backticks are used for +monospaced font; in reST, *double* backticks are for ``monospaced font``, +whereas the behavior of single backticks is defined by the default role. This +leads to the following recommendations: -- Module, function, and class names should be enclosed within ```single - backticks```. These are intended to render as hyperlinks (e.g. `numpy`). If - the hyperlinks do not render as intended, [insert reference to documentation - here]. +- Module, function, and class names should render as hyperlinks in monospaced + font (e.g. `numpy`), and depending on project settings, it may be sufficient + to enclose them in single backticks. If the hyperlink does not render as + intended, explicitly include the appropriate role and/or namespace. - References to parameters, attributes, and methods defined within the same - docstring should be enclosed within ```single backticks```. These are - currently rendered in *italics*, but there are plans to render a - ``monospaced`` hyperlink to the relevant definition in a future version of - numpydoc. + docstring should also render as hyperlinks in monospaced font. Unless the + default role is reconfigured, the recommendation is to enclosed these within + ```single backticks```. These typically render as broken links (commonly + in *italics*), but there are plans to render a ``monospaced`` hyperlink in + a future version of numpydoc. - All other text that is intended to render in ``monospaced`` font should be enclosed within ````double backticks````. From 979283191a87bf608575edcf74e7b6417ec2c73b Mon Sep 17 00:00:00 2001 From: Matt Haberland Date: Mon, 3 Jun 2024 10:51:51 -0700 Subject: [PATCH 4/5] MAINT: adjustments per review --- doc/conf.py | 2 +- doc/format.rst | 39 ++++++++++++++++++++------------------- 2 files changed, 21 insertions(+), 20 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 9bffda88..e61707c1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -139,6 +139,6 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), - "numpy": ("https://numpy.org/devdocs/", None), + "numpy": ("https://numpy.org/docs/stable/", None), "sklearn": ("https://scikit-learn.org/stable/", None), } diff --git a/doc/format.rst b/doc/format.rst index 99adcbce..92cc2d36 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -699,7 +699,7 @@ Other points to keep in mind * Equations : as discussed in the :ref:`Notes ` section above, LaTeX formatting should be kept to a minimum. Often it's possible to show equations as Python code or pseudo-code instead, which is much more readable - in a terminal. For inline display of code use double backticks, + in a terminal. For inline display of code, use double backticks like ````y = np.sin(x)````. For display with blank lines above and below, use a double colon and indent the code, like:: @@ -724,12 +724,13 @@ Other points to keep in mind (i.e. scalar types, sequence types), those arguments can be documented with type `array_like`. -* Links : Sphinx will automatically create hyperlinks to module, function, - and class documentation if a recognized name is included within single - backticks (e.g. ```numpy``` renders as `numpy`). If you need to include - other hyperlinks, note that some docstring sections are not parsed as - standard reST, and in these sections, numpydoc may become confused by - hyperlink targets such as:: +* Links : Depending on project settings, hyperlinks to documentation of + modules, classes, functions, methods, and attributes should automatically + be created if a recognized name is included within single backticks (e.g. + ```numpy``` renders as :any:`numpy`). If you need to include other + hyperlinks, note that some docstring sections are not parsed as standard + reST, and in these sections, numpydoc may become confused by hyperlink + targets such as:: .. _Example: http://www.example.com @@ -750,18 +751,18 @@ Use of backticks in reST is a common point of confusion because it is different from markdown. In most flavors of markdown, single backticks are used for monospaced font; in reST, *double* backticks are for ``monospaced font``, whereas the behavior of single backticks is defined by the default role. This -leads to the following recommendations: - -- Module, function, and class names should render as hyperlinks in monospaced - font (e.g. `numpy`), and depending on project settings, it may be sufficient - to enclose them in single backticks. If the hyperlink does not render as - intended, explicitly include the appropriate role and/or namespace. -- References to parameters, attributes, and methods defined within the same - docstring should also render as hyperlinks in monospaced font. Unless the - default role is reconfigured, the recommendation is to enclosed these within - ```single backticks```. These typically render as broken links (commonly - in *italics*), but there are plans to render a ``monospaced`` hyperlink in - a future version of numpydoc. +leads to the following style recommendations: + +- Module, class, function, method, and attribute names should render as + hyperlinks in monospaced font (e.g. :any:`numpy`); depending on project + settings, this may be accomplished simply be enclosing them in single + backticks. If the hyperlink does not render as intended, explicitly + include the appropriate role and/or namespace. +- This guide continues to recommended that parameter names be enclosed within + single backticks. Currently, this may cause parameter names to render + improperly and cause warnings, but numpydoc will soon release a feature + that causes them to render as monospaced hyperlinks to the parameter + documentation. - All other text that is intended to render in ``monospaced`` font should be enclosed within ````double backticks````. From 4b3afe9793f741db43833505ef2b7383f85fec3d Mon Sep 17 00:00:00 2001 From: Matt Haberland Date: Mon, 3 Jun 2024 11:12:38 -0700 Subject: [PATCH 5/5] MAINT: fix links to numpy --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index e61707c1..b1b2e63d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -139,6 +139,6 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), - "numpy": ("https://numpy.org/docs/stable/", None), + "numpy": ("https://numpy.org/doc/stable/", None), "sklearn": ("https://scikit-learn.org/stable/", None), }