Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: add API docs content guidelines to api docs instructions #30085

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 20, 2025
+32 −31
Merged

DOC: add API docs content guidelines to api docs instructions #30085

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a3782cd
add API docs content guidelines to api docs instructions
story645 May 20, 2025
c3987ee
move inheritance diagrams out of miscellanious to API
story645 May 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 32 additions & 31 deletions doc/devel/document.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -399,11 +399,14 @@ expression in the Matplotlib figure. In these cases, you can use the

.. _writing-docstrings:

Write docstrings
================
Write API documentation
=======================

Most of the API documentation is written in docstrings. These are comment
blocks in source code that explain how the code works.
The API reference documentation describes the library interfaces, e.g. inputs, outputs,
and expected behavior. Most of the API documentation is written in docstrings. These are
comment blocks in source code that explain how the code works. All docstrings should
conform to the `numpydoc docstring guide`_. Much of the ReST_ syntax discussed above
(:ref:`writing-rest-pages`) can be used for links and references.

.. note::

Expand All @@ -412,11 +415,11 @@ blocks in source code that explain how the code works.
you may see in the source code. Pull requests updating docstrings to
the current style are very welcome.

All new or edited docstrings should conform to the `numpydoc docstring guide`_.
Much of the ReST_ syntax discussed above (:ref:`writing-rest-pages`) can be
used for links and references. These docstrings eventually populate the
:file:`doc/api` directory and form the reference documentation for the
library.
The pages in :file:`doc/api` are purely technical definitions of
layout; therefore new API reference documentation should be added to the module
docstrings. This placement keeps all API reference documentation about a module in the
same file. These module docstrings eventually populate the :file:`doc/api` directory
and form the reference documentation for the library.

Example docstring
-----------------
Expand Down Expand Up @@ -866,6 +869,26 @@ Plots can also be directly placed inside docstrings. Details are in
An advantage of this style over referencing an example script is that the
code will also appear in interactive docstrings.

.. _inheritance-diagrams:

Generate inheritance diagrams
-----------------------------

Class inheritance diagrams can be generated with the Sphinx
`inheritance-diagram`_ directive.

.. _inheritance-diagram: https://www.sphinx-doc.org/en/master/usage/extensions/inheritance.html

Example:

.. code-block:: rst

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
:parts: 2

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
:parts: 2

.. _writing-examples-and-tutorials:

Write examples and tutorials
Expand Down Expand Up @@ -1151,28 +1174,6 @@ Use the full path for this directive, relative to the doc root at
found by users at ``http://matplotlib.org/stable/old_topic/old_info2``.
For clarity, do not use relative links.


.. _inheritance-diagrams:

Generate inheritance diagrams
-----------------------------

Class inheritance diagrams can be generated with the Sphinx
`inheritance-diagram`_ directive.

.. _inheritance-diagram: https://www.sphinx-doc.org/en/master/usage/extensions/inheritance.html

Example:

.. code-block:: rst

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
:parts: 2

.. inheritance-diagram:: matplotlib.patches matplotlib.lines matplotlib.text
:parts: 2


Navbar and style
----------------

Expand Down