diff --git a/doc/conf.py b/doc/conf.py index 9bffda88..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/devdocs/", None), + "numpy": ("https://numpy.org/doc/stable/", None), "sklearn": ("https://scikit-learn.org/stable/", None), } diff --git a/doc/format.rst b/doc/format.rst index 2f9753c5..92cc2d36 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 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. @@ -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 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:: @@ -606,6 +611,8 @@ becomes useful to have an additional **Methods** section: """ +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. @@ -690,11 +697,11 @@ 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, 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,9 +724,13 @@ 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 - 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 @@ -729,17 +740,31 @@ 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 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 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````. A more extensive example of reST markup can be found in `this example document `_;