DOCS: add links and sections to PR template

brunobeltran · brunobeltran · commit 61842d161e4a · 2020-08-25T14:31:33.000-07:00
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,12 +2,22 @@
 
 ## PR Checklist
 
-- [ ] Has Pytest style unit tests
-- [ ] Code is [Flake 8](http://flake8.pycqa.org/en/latest/) compliant
-- [ ] New features are documented, with examples if plot related
-- [ ] Documentation is sphinx and numpydoc compliant
-- [ ] Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
-- [ ] Documented in doc/api/next_api_changes/* if API changed in a backward-incompatible way
+<!-- Please remove any checkboxes that do not apply to this PR. -->
+
+Code:
+- [ ] has [pytest style](https://matplotlib.org/devel/testing.html) unit tests (and `pytest` passes).
+- [ ] is [Flake 8](https://flake8.pycqa.org/en/latest/) compliant (run `flake8` on changed files to check).
+
+New features:
+- [ ] are documented, [with examples](https://matplotlib.org/devel/documenting_mpl.html#writing-examples-and-tutorials) if plot related.
+- [ ] have an entry in `doc/users/next_whats_new/` (follow instructions in the "What's New" [README](https://github.com/matplotlib/matplotlib/blob/master/doc/users/next_whats_new/README.rst)).
+
+API Changes:
+- [ ] are documented in `doc/api/next_api_changes/` (follow instructions in the API changes [README](https://github.com/matplotlib/matplotlib/blob/master/doc/api/next_api_changes/README.rst)).
+
+Documentation:
+- [ ] is [sphinx](https://www.sphinx-doc.org/en/master/index.html) and [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) compliant (the docs should [build](https://matplotlib.org/devel/documenting_mpl.html#building-the-docs) without error).
+- [ ] conforms to Matplotlib [style conventions](https://matplotlib.org/devel/documenting_mpl.html#formatting-and-style-conventions) (and `flake8 --docstring-convention=all` [passes](https://matplotlib.org/devel/documenting_mpl.html#writing-docstrings)).
 
 <!--
 Thank you so much for your PR!  To help us review your contribution, please
@@ -39,3 +49,4 @@ the recommended next step seems overly demanding, if you would like help in
 addressing a reviewer's comments, or if you have been waiting too long to hear
 back on your PR.
 -->
+
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -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
@@ -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:
 
@@ -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.
+To quickly check that new docstrings conform to our style guide, run the
+following command on any changed files:
+
+.. code-block:: bash
+
+   $ flake8 --docstring-convention=all
+
+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.
 
