Mike's Blabberings

When using automated code-style checkers, such as pylint, we often want to check that our documentation meets certain standards in addition to the code itself. If you want to stray from PEP8 and use PythonDoc aka pydoc instead of the traditional docstring-style comments, you might struggle for a moment to find something to help enforce your standards.

Most pylint checkers use the abstract syntax tree to evaluate code style, and unfortunately, the AST skips over comments (although it does grab docstrings). So out of the box, you can check to make sure there are docstring-comments, but not that there are PythonDocs attached to a module. For reference, a pydoc-ified module looks something like:

1
2
3
4
5
6
7
8

##
# Class description
class MyClass(object):
    ##
    # Method description
    # @param p1
    def do_me(self, p1):
        pass

Because all the pydoc markup is hidden from the AST, it didn’t seem like we’d be able to check for it. Turns out, it doesn’t need to be in the AST for us to utilize pylint’s plugin architecture. There are actually a few checkers that by default work on the file itself.

With this knowledge, we can write a checker that extends pylint.checkers.BaseRawChecker and utilize pythondoc’s API to parse the file and verify that the returned ElementTree contains what we need.

You can download the implementation in pylint_pydoc_checker.py. This will parse the file and make sure that there is at least 1 top-level pythondoc description.

To activate the plugin, add this line to your .pylintrc

1
2
3
4
5
6
7
8

# List of plugins (as comma separated values of python modules names) to load,
# usually to register additional checkers.
# You can put the pylint_pydoc_checker in a modularized namespace if you wish
load-plugins=pylint_pydoc_checker
 
# Disable the message(s) with the given id(s).
# Don't show the docstring warning (C0111), since we're checking for pydoc comments
disable-msg=C0111

This does require the 2.1b6 version of pythondoc, available on effbot.

Update 2008.10.28: Modified .pylintrc setup. Thanks Larry Kincaid for pointing out the issues!