From 6ad2314da7890815ca940524b550270face291df Mon Sep 17 00:00:00 2001
From: Justin Ludwig <justin@ldwg.us>
Date: Sat, 23 Nov 2019 14:06:13 -0800
Subject: [PATCH 1/2] STY: Reword first lines of example.py docstrings

Running doc/example.py through [pydocstyle](http://www.pydocstyle.org/)
using the "numpy" conventions turns up the following violations for the
module docstring:

* D205: 1 blank line required between summary line and description
  (found 0)
* D400: First line should end with a period (not 'd')
* D404: First word of the docstring should not be `This`
* D415: First line should end with a period, question mark, or
  exclamation point (not 'd')

And the following violation for the `foo()` function docstring:

* D401: First line should be in imperative mood; try rephrasing (found
  'A')

This change slightly rewords the first line of both docstrings to better
model how docstrings should begin:

1. It reformats the module docstring to place the first sentence on its
own line, and remove the superflous "This is the" introduction.
2. It rewords the `foo()` function docstring to rephrase the first line
as a command (following the PEP 257 convention).

After this change, pydocstyle finds no violations.
---
 doc/example.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/doc/example.py b/doc/example.py
index c051d4f2..33c55ccb 100644
--- a/doc/example.py
+++ b/doc/example.py
@@ -1,6 +1,7 @@
-"""This is the docstring for the example.py module.  Modules names should
-have short, all-lowercase names.  The module name may have underscores if
-this improves readability.
+"""Docstring for the example.py module.
+
+Modules names should have short, all-lowercase names.  The module name may
+have underscores if this improves readability.
 
 Every module should have a docstring at the very top of the file.  The
 module's docstring may extend over multiple lines.  If your docstring does
@@ -35,7 +36,7 @@
 
 
 def foo(var1, var2, long_var_name='hi'):
-    r"""A one-line summary that does not use variable names.
+    r"""Summarize the function in one line.
 
     Several sentences providing an extended description. Refer to
     variables using back-ticks, e.g. `var`.

From 7aa05958b4523afc4c3f8a0a6ccd14783fbd148f Mon Sep 17 00:00:00 2001
From: Justin Ludwig <justin@ldwg.us>
Date: Sun, 24 Nov 2019 11:45:37 -0800
Subject: [PATCH 2/2] BLD: run pydocstyle on example.py in travis

---
 .travis.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index f6dd4cca..80f6e477 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -16,7 +16,7 @@ cache:
 before_install:
   - sudo apt-get install texlive texlive-latex-extra latexmk dvipng
   - pip install --upgrade pip setuptools  # Upgrade pip and setuptools to get ones with `wheel` support
-  - pip install pytest pytest-cov numpy matplotlib sphinx${SPHINX_SPEC} codecov
+  - pip install pytest pytest-cov pydocstyle numpy matplotlib sphinx${SPHINX_SPEC} codecov
 script:
   - |
     python setup.py sdist
@@ -28,6 +28,7 @@ script:
   - echo '! python -m numpydoc numpydoc.tests.test_main._invalid_docstring' | bash
   - python -m numpydoc --validate numpydoc.tests.test_main._capture_stdout
   - echo '! python -m numpydoc --validate numpydoc.tests.test_main._docstring_with_errors' | bash
+  - pydocstyle --convention numpy ../doc/example.py
   # Build documentation
   - |
     cd ../doc