All tests pass for now.

Author: Nurdok

README.rst

@@ -10,11 +10,6 @@ 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.
 
 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 <https://pydocstyle.readthedocs.io>`_.
+* `Read the full documentation here <https://pydocstyle.org>`_.
 
 * `Fork pydocstyle on GitHub <http://github.com/PyCQA/pydocstyle>`_.
 

requirements/tests.txt

@@ -1,4 +1,5 @@
 pytest==2.7.3
 pytest-pep8
 mock
-tox
+tox
+pathlib

setup.py

@@ -3,7 +3,7 @@
 from setuptools import setup
 
 
-with open(os.path.join('src', 'pydocstyle', 'pydocstyle.py')) as f:
+with open(os.path.join('src', 'pydocstyle', 'utils.py')) as f:
     for line in f:
         if line.startswith('__version__'):
             version = eval(line.split('=')[-1])

src/__init__.py

@@ -5,12 +5,15 @@
 http://github.com/PyCQA/pydocstyle
 
 """
-from __future__ import with_statement
 
-import logging
 
-log = logging.getLogger(__name__)
+__all__ = ()
 
 
-__version__ = '1.1.0-rc1'
-__all__ = ()
+def main():
+    from pydocstyle import cli
+    cli.main()
+
+
+if __name__ == '__main__':
+    main()

src/pydocstyle/pydocstyle.py renamed to src/main.py

@@ -1,16 +1,20 @@
+"""Parsed source code checkers for docstring violations."""
+
 import ast
 import string
 import sys
 import tokenize as tk
 from itertools import takewhile
 from re import compile as re
 
-import violations
-from config import IllegalConfiguration
+from . import violations
+from .config import IllegalConfiguration
 # TODO: handle
-from parser import *
-from pydocstyle import log
-from utils import is_blank
+from .parser import *
+from .utils import log, is_blank
+
+
+__all__ = ('check', )
 
 
 # If possible (python >= 3.2) use tokenize.open to open files, so PEP 263
@@ -386,7 +390,7 @@ def check(filenames, select=None, ignore=None):
 
     Example
     -------
-    >>> check([ppydocstyle.py.py], checked_codes=['D100'])
+    >>> check(['pydocstyle.py'], checked_codes=['D100'])
     <generator object check at 0x...>
 
     """

src/pydocstyle/checker.py

@@ -1,10 +1,14 @@
+"""Command line interface for pydocstyle."""
 import logging
 import sys
 
-from pydocstyle import log
-from violations import Error
-from config import ConfigurationParser, IllegalConfiguration
-from checker import check
+from .utils import log
+from .violations import Error
+from .config import ConfigurationParser, IllegalConfiguration
+from .checker import check
+
+
+__all__ = ('main', )
 
 
 class ReturnCode(object):
@@ -59,6 +63,12 @@ def run_pydocstyle(use_pep257=False):
 
 
 def main(use_pep257=False):
+    """Run pydocstyle as a script.
+
+    `use_pep257` is True if the script was invoked with the deprecated script
+    name `pep257`, in which case a deprecation warning will be printed.
+
+    """
     try:
         sys.exit(run_pydocstyle(use_pep257))
     except KeyboardInterrupt:

src/pydocstyle/cli.py

@@ -1,3 +1,5 @@
+"""Configuration file parsing and utilities."""
+
 import copy
 import itertools
 import os
@@ -11,8 +13,8 @@
     from configparser import RawConfigParser
 
 
-from pydocstyle import __version__, log
-from violations import ErrorRegistry, conventions
+from .utils import __version__, log
+from .violations import ErrorRegistry, conventions
 
 
 def check_initialized(method):

src/pydocstyle/config.py

@@ -1,3 +1,5 @@
+"""Python code parser."""
+
 import logging
 import sys
 import textwrap
@@ -36,6 +38,8 @@ def humanize(string):
 
 
 class Value(object):
+    """A generic object with a list of preset fields."""
+
     def __init__(self, *args):
         vars(self).update(zip(self._fields, args))
 
@@ -52,6 +56,8 @@ def __repr__(self):
 
 
 class Definition(Value):
+    """A Python source code definition (could be class, function, etc)."""
+
     _fields = ('name', '_source', 'start', 'end', 'decorators', 'docstring',
                'children', 'parent')
 
@@ -85,6 +91,8 @@ def __str__(self):
 
 
 class Module(Definition):
+    """A Python source code module."""
+
     _fields = ('name', '_source', 'start', 'end', 'decorators', 'docstring',
                'children', 'parent', '_all', 'future_imports')
     is_public = True
@@ -101,30 +109,39 @@ class Package(Module):
 
 
 class Function(Definition):
+    """A Python source code function."""
+
     _nest = staticmethod(lambda s: {'def': NestedFunction,
                                     'class': NestedClass}[s])
 
     @property
     def is_public(self):
+        """Return True iff this function should be considered public."""
         if self.all is not None:
             return self.name in self.all
         else:
             return not self.name.startswith('_')
 
 
 class NestedFunction(Function):
+    """A Python source code nested function."""
+
     is_public = False
 
 
 class Method(Function):
+    """A Python source code method."""
+
     @property
     def is_magic(self):
+        """Return True iff this method is a magic method (e.g., `__str__`)."""
         return (self.name.startswith('__') and
                 self.name.endswith('__') and
                 self.name not in VARIADIC_MAGIC_METHODS)
 
     @property
     def is_public(self):
+        """Return True iff this method should be considered public."""
         # Check if we are a setter/deleter method, and mark as private if so.
         for decorator in self.decorators:
             # Given 'foo', match 'foo.bar' but not 'foobar' or 'sfoo'
@@ -137,14 +154,19 @@ def is_public(self):
 
 
 class Class(Definition):
+    """A Python source code class."""
+
     _nest = staticmethod(lambda s: {'def': Method, 'class': NestedClass}[s])
     is_public = Function.is_public
     is_class = True
 
 
 class NestedClass(Class):
+    """A Python source code nested class."""
+
     @property
     def is_public(self):
+        """Return True iff this class should be considered public."""
         return (not self.name.startswith('_') and
                 self.parent.is_class and
                 self.parent.is_public)
@@ -160,7 +182,10 @@ class Decorator(Value):
 
 
 class AllError(Exception):
+    """Raised when there is a problem with __all__ when parsing."""
+
     def __init__(self, message):
+        """Initialize the error with a more specific message."""
         Exception.__init__(
             self, message + textwrap.dedent("""
                 That means pydocstyle cannot decide which definitions are
@@ -207,7 +232,10 @@ def __init__(self, *args):
 
 
 class Parser(object):
+    """A Python source code parser."""
+
     def parse(self, filelike, filename):
+        """Parse the given file-like object and return its Module object."""
         # TODO: fix log
         self.log = logging.getLogger()
         self.source = filelike.readlines()
@@ -221,6 +249,7 @@ def parse(self, filelike, filename):
 
     # TODO: remove
     def __call__(self, *args, **kwargs):
+        """Call the parse method."""
         return self.parse(*args, **kwargs)
 
     current = property(lambda self: self.stream.current)
@@ -437,6 +466,7 @@ def parse_definition(self, class_):
         return definition
 
     def check_current(self, kind=None, value=None):
+        """Verify the current token is of type `kind` and equals `value`."""
         msg = textwrap.dedent("""
         Unexpected token at line {self.line}:
 

src/pydocstyle/parser.py

@@ -1,10 +1,19 @@
+"""Parser tests."""
+
 import six
 import textwrap
 from pydocstyle.parser import Parser
 
 
 class CodeSnippet(six.StringIO):
+    """A code snippet.
+
+    Automatically wraps snippet as a file-like object and handles line wraps.
+
+    """
+
     def __init__(self, code_string):
+        """Initialize the object."""
         six.StringIO.__init__(self, textwrap.dedent(code_string))