diff options
| author | Justin Ludwig <justinludwig@gmail.com> | 2019-11-27 06:36:25 -0800 |
|---|---|---|
| committer | Eric Larson <larson.eric.d@gmail.com> | 2019-11-27 09:36:25 -0500 |
| commit | 9388b7fb8b4d8bb5d3806e23baa6e713528d9e69 (patch) | |
| tree | ffda6ccbff9e2ee079610633f92579ac1f79ec5d | |
| parent | d5323aeec5b98d2594805a9d3add6e1613d18a60 (diff) | |
| download | numpydoc-9388b7fb8b4d8bb5d3806e23baa6e713528d9e69.tar.gz | |
STY: Reword first lines of example.py docstrings (#246)
* 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.
* BLD: run pydocstyle on example.py in travis
| -rw-r--r-- | .travis.yml | 3 | ||||
| -rw-r--r-- | doc/example.py | 9 |
2 files changed, 7 insertions, 5 deletions
diff --git a/.travis.yml b/.travis.yml index f6dd4cc..80f6e47 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 diff --git a/doc/example.py b/doc/example.py index c051d4f..33c55cc 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 @@ import matplotlib.pyplot as plt 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`. |