Merge remote-tracking branch 'refs/remotes/PyCQA/master' into numpy-conventions

# Conflicts:
#	src/pydocstyle.py
#	src/tests/test_definitions.py

Author: shacharoo

.gitignore

@@ -43,6 +43,7 @@ docs/_*
 
 # virtualenv
 venv/
+.venvs/
 
 # generated rst
 docs/snippets/error_code_table.rst

.travis.yml

@@ -9,8 +9,6 @@ install: pip install tox
 script: tox
 matrix:
   include:
-    - python: 2.6
-      env: TOXENV=py26
     - python: 2.7
       env: TOXENV=py27
     - python: 3.3
@@ -21,7 +19,5 @@ matrix:
       env: TOXENV=py35
     - python: pypy
       env: TOXENV=pypy
-    - python: pypy3
-      env: TOXENV=pypy3
     - python: 2.7
       env: TOXENV=docs

README.rst

@@ -10,12 +10,7 @@ docstring conventions.
 `PEP 257 <http://www.python.org/dev/peps/pep-0257/>`_ out of the box, but it
 should not be considered a reference implementation.
 
-The framework for checking docstring style is flexible, and
-custom checks can be easily added, for example to cover
-NumPy `docstring conventions
-<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
-
-**pydocstyle** supports Python 2.6, 2.7, 3.3, 3.4, 3.5, pypy and pypy3.
+**pydocstyle** supports Python 2.7, 3.3, 3.4, 3.5 and pypy.
 
 Quick Start
 -----------
@@ -27,16 +22,19 @@ Install
 
     pip install pydocstyle
 
+
 Run
-^^^
+^^^^
 
 .. code::
 
     $ pydocstyle test.py
     test.py:18 in private nested class `meta`:
             D101: Docstring missing
-    test.py:22 in public method `method`:
-            D102: Docstring missing
+    test.py:27 in public function `get_user`:
+        D300: Use """triple double quotes""" (found '''-quotes)
+    test:75 in public function `init_database`:
+        D201: No blank lines allowed before function docstring (found 1)
     ...
 
 
@@ -50,7 +48,7 @@ Links
     :target: https://readthedocs.org/projects/pydocstyle/?badge=latest
     :alt: Documentation Status
 
-* `Read the full documentation here <http://pydocstyle.readthedocs.org>`_.
+* `Read the full documentation here <http://pydocstyle.org>`_.
 
 * `Fork pydocstyle on GitHub <http://github.com/PyCQA/pydocstyle>`_.
 

docs/conf.py

@@ -18,7 +18,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
 
 # -- General configuration ------------------------------------------------
 
@@ -268,7 +268,7 @@
 
 
 def generate_error_code_table():
-    from pydocstyle import ErrorRegistry
+    from pydocstyle.violations import ErrorRegistry
     with open(os.path.join('snippets', 'error_code_table.rst'), 'wt') as outf:
         outf.write(ErrorRegistry.to_rst())
 

docs/error_codes.rst

@@ -16,3 +16,9 @@ check only error codes that are part of the `PEP257
 
 All of the above error codes are checked for by default except for D203,
 D212, D213 and D404.
+
+
+Publicity
+---------
+
+.. include:: snippets/publicity.rst

docs/index.rst

@@ -1,15 +1,15 @@
 pydocstyle's documentation
 ==========================
 
-(formerly pep257)
-
 **pydocstyle** is a static analysis tool for checking compliance with Python
 docstring conventions.
 
 **pydocstyle** supports most of
 `PEP 257 <http://www.python.org/dev/peps/pep-0257/>`_ out of the box, but it
 should not be considered a reference implementation.
 
+**pydocstyle** supports Python 2.7, 3.3, 3.4, 3.5 and pypy.
+
 
 .. include:: quickstart.rst
 

docs/quickstart.rst

@@ -14,8 +14,10 @@ Quick Start
         $ pydocstyle test.py
         test.py:18 in private nested class `meta`:
                 D101: Docstring missing
-        test.py:22 in public method `method`:
-                D102: Docstring missing
+        test.py:27 in public function `get_user`:
+            D300: Use """triple double quotes""" (found '''-quotes)
+        test:75 in public function `init_database`:
+            D201: No blank lines allowed before function docstring (found 1)
         ...
 
 3. Fix your code :)

docs/release_notes.rst

@@ -7,20 +7,75 @@ Release Notes
 Current Development Version
 ---------------------------
 
+Major Updates
+
+* Support for Python 2.6 has been dropped (#206, #217).
+* Support for PyPy3 has been temporarily dropped, until it will be
+  equivalent to CPython 3.3+ and supported by ``pip`` (#223).
+* Support for the ``pep257`` console script has been dropped. Only the
+  ``pydocstyle`` console script should be used (#216, #218).
+
+New Features
+
+* Decorator-based skipping via ``--ignore-decorators`` has been added (#204).
+* Support for using pycodestyle style wildcards has been added (#72, #209).
+* Superfluous opening quotes are now reported as part of D300 (#166, #225).
+
+Bug Fixes
+
+* Made parser more robust to bad source files (#168, #214)
+* Modules are now considered private if their name starts with a single
+  underscore. This is a bugfix where "public module" (D100) was reported
+  regardless of module name (#199, #222).
+
+
+1.1.1 - October 4th, 2016
+-------------------------
+
+Bug Fixes
+
+* Fixed an issue where the ``flake8-docstrings`` failed when accessing some
+  public API from ``pydocstyle``.
+
+
+1.1.0 - September 29th, 2016
+----------------------------
+
+Major Updates
+
+* ``pydocstyle`` is no longer a single file. This might make it difficult for
+  some users to just add it to their project, but the project has reached
+  certain complexity where splitting it into modules was necessary (#200).
+
 New Features
 
 * Added the optional error codes D212 and D213, for checking whether
   the summary of a multi-line docstring starts at the first line,
   respectively at the second line (#174).
 
-* Added D404 - First word of the docstring should not be `This`. It is turned
+* Added D404 - First word of the docstring should not be "This". It is turned
   off by default (#183).
 
+* Added the ability to ignore specific function and method docstrings with
+  inline comments:
+
+    1. "# noqa" skips all checks.
+
+    2. "# noqa: D102,D203" can be used to skip specific checks.
+
 Bug Fixes
 
+* Fixed an issue where file paths were printed in lower case (#179, #181).
+
 * The error code D300 is now also being reported if a docstring has
   uppercase literals (``R`` or ``U``) as prefix (#176).
 
+* Fixed a bug where an ``__all__`` error was reported when ``__all__`` was
+  imported from another module with a different name (#182, #187).
+
+* Fixed a bug where ``raise X from Y`` syntax caused ``pydocstyle`` to crash
+  (#196, #200).
+
 1.0.0 - January 30th, 2016
 --------------------------
 

docs/snippets/cli.rst

@@ -17,11 +17,12 @@ Usage
       --count               print total number of errors to stdout
       --select=<codes>      choose the basic list of checked errors by specifying
                             which errors to check for (with a list of comma-
-                            separated error codes). for example:
-                            --select=D101,D202
+                            separated error codes or prefixes). for example:
+                            --select=D101,D2
       --ignore=<codes>      choose the basic list of checked errors by specifying
                             which errors to ignore (with a list of comma-separated
-                            error codes). for example: --ignore=D101,D202
+                            error codes or prefixes). for example:
+                            --ignore=D101,D2
       --convention=<name>   choose the basic list of checked errors by specifying
                             an existing convention. Possible conventions: pep257
       --add-select=<codes>  amend the list of errors to check for by specifying
@@ -36,7 +37,20 @@ Usage
                             search only dirs that exactly match <pattern> regular
                             expression; default is --match-dir='[^\.].*', which
                             matches all dirs that don't start with a dot
+      --ignore-decorators=<decorators>
+                            ignore any functions or methods that are decorated by
+                            a function with a name fitting the <decorators>
+                            regular expression; default is --ignore-decorators=''
+                            which does not ignore any decorated functions.
 
+.. note::
+
+    When using any of the ``--select``, ``--ignore``, ``--add-select``, or
+    ``--add-ignore`` command line flags, it is possible to pass a prefix for an
+    error code. It will be expanded so that any code begining with that prefix
+    will match. For example, running the command ``pydocstyle --ignore=D4``
+    will ignore all docstring content issues as their error codes begining with
+    "D4" (i.e. D400, D401, D402, D403, and D404).
 
 Return Code
 ^^^^^^^^^^^

docs/snippets/config.rst

@@ -32,6 +32,7 @@ Available options are:
 * ``add_ignore``
 * ``match``
 * ``match_dir``
+* ``ignore_decorators``
 
 See the :ref:`cli_usage` section for more information.
 

docs/snippets/in_file.rst

@@ -0,0 +1,15 @@
+``pydocstyle`` supports inline commenting to skip specific checks on
+specific functions or methods. The supported comments that can be added are:
+
+1. ``"# noqa"`` skips all checks.
+
+2. ``"# noqa: D102,D203"`` can be used to skip specific checks. Note that
+   this is compatible with skips from `flake8 <http://flake8.pycqa.org/>`_,
+   e.g. ``# noqa: D102,E501,D203``.
+
+For example, this will skip the check for a period at the end of a function
+docstring::
+
+    >>> def bad_function():  # noqa: D400
+    ...     """Omit a period in the docstring as an exception"""
+    ...     pass

docs/snippets/publicity.rst

@@ -0,0 +1,41 @@
+The D1xx group of errors deals with missing docstring in public constructs:
+modules, classes, methods, etc. It is important to note how publicity is
+determined and what its effects are.
+
+
+How publicity is determined
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Publicity for all constructs is determined as follows: a construct is
+considered *public* if -
+
+1. Its immediate parent is public *and*
+2. Its name does not contain a single leading underscore.
+
+A construct's immediate parent is the construct that contains it. For example,
+a method's parent is a class object. A class' parent is usually a module, but
+might also be a function, method, etc. A module can either have no parent, or
+it can have a parent that is a package.
+
+In order for a construct to be considered public, its immediate parent must
+also be public. Since this definition is recursive, it means that *all* of its
+parents need to be public. The corollary is that if a construct is considered
+private, then all of its descendants are also considered private. For example,
+a class called ``_Foo`` is considered private. A method ``bar`` in ``_Foo`` is
+also considered private since its parent is a private class, even though its
+name does not begin with a single underscore.
+
+
+How publicity affects error reports
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The immediate effect of a construct being determined as private is that no
+D1xx errors will be reported for it (or its children, as the previous section
+explains). A private method, for instance, will not generate a D102 error, even
+if it has no docstring.
+
+However, it is important to note that while docstring are optional for private
+construct, they are still required to adhere to your style guide. So if a
+private module `_foo.py` does not have a docstring, it will not generate a
+D100 error, but if it *does* have a docstring, that docstring might generate
+other errors.

docs/usage.rst

@@ -17,3 +17,9 @@ Configuration Files
 ^^^^^^^^^^^^^^^^^^^
 
 .. include:: snippets/config.rst
+
+
+In-file configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: snippets/in_file.rst

requirements.txt

@@ -1,2 +1,4 @@
 -r requirements/docs.txt
 -r requirements/tests.txt
+-r requirements/test_env.txt
+-r requirements/runtime.txt

requirements/runtime.txt

@@ -0,0 +1 @@
+tox

requirements/test_env.txt

@@ -1,4 +1,4 @@
-pytest==2.7.3
-pytest-pep8
-mock
-tox
+pytest==3.0.2
+pytest-pep8==1.0.6
+mock==2.0.0
+pathlib

requirements/tests.txt

@@ -1,2 +1,19 @@
+[bumpversion]
+current_version = 2.0.0rc
+commit = True
+parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)((?P<release>.*))?
+serialize = 
+	{major}.{minor}.{patch}{release}
+	{major}.{minor}.{patch}
+
 [wheel]
 universal = 1
+
+[bumpversion:part:release]
+optional_value = production
+values = 
+	rc
+	production
+
+[bumpversion:file:src/pydocstyle/utils.py]
+

setup.cfg

@@ -3,7 +3,9 @@
 from setuptools import setup
 
 
-with open(os.path.join('src', 'pydocstyle.py')) as f:
+this_dir = os.path.dirname(__file__)
+
+with open(os.path.join(this_dir, 'src', 'pydocstyle', 'utils.py')) as f:
     for line in f:
         if line.startswith('__version__'):
             version = eval(line.split('=')[-1])
@@ -27,12 +29,11 @@
         'License :: OSI Approved :: MIT License',
     ],
     keywords='pydocstyle, PEP 257, pep257, PEP 8, pep8, docstrings',
+    packages=('pydocstyle',),
     package_dir={'': 'src'},
-    py_modules=['pydocstyle'],
     entry_points={
         'console_scripts': [
-            'pydocstyle = pydocstyle:main',
-            'pep257 = pydocstyle:main_pep257',
+            'pydocstyle = pydocstyle.cli:main',
         ],
     },
 )