Skip to content
This repository was archived by the owner on Nov 3, 2023. It is now read-only.

Commit 5cd4857

Browse files
author
Vladimir Keleshev
committed
New, updated README.rst
1 parent 3ac580f commit 5cd4857

File tree

2 files changed

+120
-136
lines changed

2 files changed

+120
-136
lines changed

‎README.md

Lines changed: 0 additions & 136 deletions
This file was deleted.

‎README.rst

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
PEP 257 docstring style checker
2+
===========================================================
3+
4+
**pep257** is a static analysis tool for checking
5+
compliance with Python `PEP 257
6+
<http://www.python.org/dev/peps/pep-0257/>`_.
7+
8+
The framework for checking docstring style is flexible, and
9+
custom checks can be easily added, for example to cover
10+
NumPy `docstring conventions
11+
<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
12+
13+
Installation
14+
-----------------------------------------------------------
15+
16+
Use `pip <http://pip-installer.org>`_ or easy_install::
17+
18+
pip install pep257
19+
20+
Alternatively, you can use ``pep257.py`` source file
21+
directly--it is self-contained.
22+
23+
**pep257** is tested with Python 2.5, 2.6, 2.7, 3.2, 3.3
24+
25+
Example
26+
-----------------------------------------------------------
27+
28+
.. code::
29+
30+
$ pep257 --help
31+
Usage: pep257 [options] [<file|dir>...]
32+
33+
Options:
34+
--version show program's version number and exit
35+
-h, --help show this help message and exit
36+
-e, --explain show explanation of each error
37+
-s, --source show source for each error
38+
--ignore=<codes> ignore a list comma-separated error codes, for
39+
example: --ignore=D101,D202
40+
--match=<pattern> check only files that exactly match <pattern> regular
41+
expression; default is --match='(?!test_).*\.py' which
42+
matches files that don't start with 'test_' but end
43+
with '.py'
44+
--match-dir=<pattern>
45+
search only dirs that exactly match <pattern> regular
46+
expression; default is --match-dir='[^\.].*', which
47+
matches all dirs that don't start with a dot
48+
49+
$ pep257 test.py
50+
test.py:18 in private nested class `meta`:
51+
D101: Docstring missing
52+
test.py:22 in public method `method`:
53+
D102: Docstring missing
54+
...
55+
56+
$ pep257 test.py --explain
57+
test.py:18 in private nested class `meta`:
58+
D101: Docstring missing
59+
60+
All modules should normally have docstrings. [...] all functions and
61+
classes exported by a module should also have docstrings. Public
62+
methods (including the __init__ constructor) should also have
63+
docstrings.
64+
65+
Note: Public (exported) definitions are either those with names listed
66+
in __all__ variable (if present), or those that do not start
67+
with a single underscore.
68+
...
69+
70+
$ pep257 test.py --source
71+
test.py:15 in public class `class_`:
72+
D101: Docstring missing
73+
74+
15: class class_:
75+
16:
76+
...
77+
78+
Error codes
79+
-----------------------------------------------------------
80+
81+
All **pep257** errors have unique codes. All codes start with a capital D and
82+
are grouped as follows:
83+
84+
+--------------+--------------------------------------------------------------+
85+
| **Missing docstrings** |
86+
+--------------+--------------------------------------------------------------+
87+
| D10{0,1,2,3} | Public {module,class,method,function} missing. |
88+
+--------------+--------------------------------------------------------------+
89+
| **Whitespace issues** |
90+
+--------------+--------------------------------------------------------------+
91+
| D200 | One-line docstrings should fit on one line with quotes. |
92+
+--------------+--------------------------------------------------------------+
93+
| D20{1,2} | No blank lines allowed {before,after} docstring. |
94+
+--------------+--------------------------------------------------------------+
95+
| D20{3,4} | 1 blank required {before,after} class docstring. |
96+
+--------------+--------------------------------------------------------------+
97+
| D205 | Blank line required between one-line summary and description.|
98+
+--------------+--------------------------------------------------------------+
99+
| D206 | Docstring should be indented with spaces, not tabs. |
100+
+--------------+--------------------------------------------------------------+
101+
| D20{7,8} | Docstring {under,over}-indented. |
102+
+--------------+--------------------------------------------------------------+
103+
| D209 | Multi-line docstring should end with 1 blank line. |
104+
+--------------+--------------------------------------------------------------+
105+
| **Quotes issues** |
106+
+--------------+--------------------------------------------------------------+
107+
| D300 | Use """triple double quotes""". |
108+
+--------------+--------------------------------------------------------------+
109+
| D301 | Use r""" if any backslashes in your docstring. |
110+
+--------------+--------------------------------------------------------------+
111+
| D302 | Use u""" for Unicode docstrings (Python 2 only). |
112+
+--------------+--------------------------------------------------------------+
113+
| **Docstring content issues** |
114+
+--------------+--------------------------------------------------------------+
115+
| D400 | First line should end with a period. |
116+
+--------------+--------------------------------------------------------------+
117+
| D401 | First line should be in imperative mood. |
118+
+--------------+--------------------------------------------------------------+
119+
| D402 | First line should not be the function's "signature". |
120+
+--------------+--------------------------------------------------------------+

0 commit comments

Comments
 (0)