Skip to content

DOCS: add links and sections to PR template #18348

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

Closed
wants to merge 1 commit into from
Closed

DOCS: add links and sections to PR template #18348

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
21 changes: 16 additions & 5 deletions doc/devel/documenting_mpl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ it, use
.. code-block:: sh

make SPHINXOPTS= html

On Windows the arguments must be at the end of the statement:

.. code-block:: bat
Expand All @@ -131,8 +131,8 @@ On Windows, either use the format shown above or set options as environment vari

.. code-block:: bat

set O=-W --keep-going -j4
make html
set O=-W --keep-going -j4
make html

.. _writing-rest-pages:

Expand Down Expand Up @@ -358,9 +358,20 @@ 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`_.
All new or edited docstrings should conform to the `numpydoc docstring guide`_,
and to the guide below wherever the numpydoc guide is ambiguous.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
and to the guide below wherever the numpydoc guide is ambiguous.
with the adaptions and clarifications listed below.

In some points we're intentionally deviating from numpydoc, e.g. usage of optional.

To quickly check that new docstrings conform to our style guide, run the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To quickly check that new docstrings conform to our style guide, run the
To check that new docstrings conform to our style guide, run the

"quickly" - this takes 3min CPU time on my PC.

following command on any changed files:

.. code-block:: bash

$ flake8 --docstring-convention=all
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we have to modify the standards from the .flake8 config file?


Note that this linter requires ``flake8-docstrings`` and ``pydocstyle<4`` to be
installed.

Much of the ReST_ syntax discussed above (:ref:`writing-rest-pages`) can be
used for links and references. These docstrings eventually populate the
used for links and references. These docstrings eventually populate the
:file:`doc/api` directory and form the reference documentation for the
library.

Expand Down