http://dolphm.com/pep257-good-python-docstrings-by-example/

good_docstrings.py

# -*- coding: utf-8 -*-
"""Demonstrate high quality docstrings.

Module-level docstrings appear as the first "statement" in a module. Remember,
that while strings are regular Python statements, comments are not, so an
inline comment may precede the module-level docstring.

After importing a module, you can access this special string object through the
``__doc__`` attribute; yes, it's actually available as a runtime attribute,
despite not being given an explicit name! The ``__doc__`` attribute is also
what is rendered when you call ``help()`` on a module, or really any other
object in Python.

You can also document a package using the module-level docstring in the
package's ``__init__.py`` file.

"""


def main():
    """Illustrate function-level docstring.

    Note that all docstrings begin with a one-line summary. The summary is
    written in the imperative mood ("do", "use", "find", "return", "render",
    etc) and ends with a period. The method signature is not, in any way,
    duplicated into the comments (that would be difficult to maintain).

    All subsequent paragraphs in a docstring are indented exactly the same as
    the summary line. The same applies to the closing quotation marks.

    """
    docs = Documentation()
    help(docs.__module__)


class Documentation(object):
    """Illustrate class-level docstring.

    Classes use a special whitespace convention: the opening and closing quotes
    are preceded and followed by a blank line, respectively. No other
    docstrings should be preceded or followed by anything but code.

    A blank line at the end of a multi-line docstring before the closing
    quotation marks simply makes it easier for tooling to auto-format
    paragraphs (wrapping them at 79 characters, per PEP8), without the closing
    quotation marks interfering. For example, in Vim, you can use `gqip` to
    "apply text formatting inside the paragraph." In Emacs, the equivalent
    would be the `fill-paragraph` command. While it's not required, the
    presence of a blank line is quite common and much appreciated. Regardless,
    the closing quotation marks should certainly be on a line by themselves.

    """

    def __init__(self):
        """Illustrate method-level docstring.

        All public callables should have docstrings, including magic methods
        like ``__init__()``.

        You'll notice that all these docstrings are wrapped in triple double
        quotes, as opposed to just "double quotes", 'single quotes', or
        '''triple single quotes.''' This is a convention for consistency and
        readability. However, there are two edge cases worth knowing about
        which I'll illustrate in just a moment.

        """
        super(Documentation, self).__init__()

    def oneliner(self):
        """Illustrate one line docstring, including the quotation marks."""
        return self.oneliner.__doc__

    def backslashes(self):
        r"""Illustrate raw triple double quotes for \backslashes\."""
        return self.backslashes.__doc__

    def __unicode__(self):
        u"""In Python 2, use Unicode triple double quotes for Ůňïčøđê."""
        return self.__unicode__.__doc__


if __name__ == '__main__':
    # No need for a docstring here, but an inline comment explaining that this
    # will only be executed when this module is run directly might be useful.
    # Try running this module!
    main()

pep257_help

$ pep257 --help
Usage: pep257 [options] [<file|dir>...]

Options:
--version             show program's version number and exit
-h, --help            show this help message and exit
-e, --explain         show explanation of each error
-s, --source          show source for each error
--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
--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
--convention=<name>   choose the basic list of checked errors by specifying
                        an existing convention. for example:
                        --convention=pep257
--add-select=<codes>  amend the list of errors to check for by specifying
                        more error codes to check.
--add-ignore=<codes>  amend the list of errors to check for by specifying
                        more error codes to ignore.
--match=<pattern>     check only files that exactly match <pattern> regular
                        expression; default is --match='(?!test_).*\.py' which
                        matches files that don't start with 'test_' but end
                        with '.py'
--match-dir=<pattern>
                        search only dirs that exactly match <pattern> regular
                        expression; default is --match-dir='[^\.].*', which
                        matches all dirs that don't start with a dot
-d, --debug           print debug information
-v, --verbose         print status information
--count               print total number of errors to stdout

hi

Some updates in my fork that includes a correction of the issue highlighted above.

Fixed! I never got notified about these comments until @doolio's - thanks for the feedback! Glad this was helpful.

Glad to help. Though with that fix the class docstring would need to be amended too specifically the part that states "the opening and closing quotes are preceded and followed by a blank line".

Glad this was helpful.

Yes, very helpful. Thanks.