Tool for automatically check docstring style accor

Tools like pep8 can check source code style, but they don't check if docstrings are fromatted according to pep257, pep287. Are there such tools?

Update

I decided to implement such a static analysis tool on my own, see:

https://github.com/GreenSteam/pep257

Right now, most of pep257 is covered. Design was heavily influenced by mentioned pep8 tool.

回答1:

I don't know of any static analysis tool for python doc strings. I actually started building one shortly after getting started with PyLint but quickly gave up.

PyLint has a plugin system and a doc string plugin is doable if you wanted to put the work in to make the PEPs executable.

PyLint "plugins" are called checkers and come in two forms: those working with the source file as a raw text document and those working with it as an AST. I made my attempt starting from the AST. This may have been a mistake in retrospect.

Here's what I had:

class DocStringChecker(BaseChecker):
    """
    PyLint AST based checker to eval compliance with PEP 257-ish conventions.
    """
    __implements__ = IASTNGChecker

    name = 'doc_string_checker'
    priority = -1
    msgs = {'W9001': ('One line doc string on >1 lines',
                     ('Used when a short doc string is on multiple lines')),
            'W9002': ('Doc string does not end with "." period',
                     ('Used when a doc string does not end with a period')),
            'W9003': ('Not all args mentioned in doc string',
                     ('Used when not all arguments are in the doc string ')),
            'W9004': ('triple quotes',
                     ('Used when doc string does not use """')),
           }
    options = ()

    def visit_function(self, node):
        if node.doc: self._check_doc_string(node)

    def visit_module(self, node):
        if node.doc: self._check_doc_string(node)

    def visit_class(self, node):
        if node.doc: self._check_doc_string(node)

    def _check_doc_string(self, node):
        self.one_line_one_one_line(node)
        self.has_period(node)
        self.all_args_in_doc(node)

    def one_line_one_one_line(self,node):
        """One line docs (len < 80) are on one line"""
        doc = node.doc
        if len(doc) > 80: return True
        elif sum(doc.find(nl) for nl in ('\n', '\r', '\n\r')) == -3: return True
        else:
            self.add_message('W9001', node=node, line=node.tolineno)

    def has_period(self,node):
        """Doc ends in a period"""
        if not node.doc.strip().endswith('.'):
            self.add_message('W9002', node=node, line=node.tolineno)

    def all_args_in_doc(self,node):
        """All function arguments are mentioned in doc"""
        if not hasattr(node, 'argnames'): return True
        for arg in node.argnames:
            if arg != 'self' and arg in node.doc: continue
            else: break
        else: return True
        self.add_message('W9003', node=node, line=node.tolineno)

    def triple_quotes(self,node): #This would need a raw checker to work b/c the AST doesn't use """
        """Doc string uses tripple quotes"""
        doc = node.doc.strip()
        if doc.endswith('"""') and doc.startswith('"""'): return True
        else: self.add_message('W9004', node=node, line=node.tolineno)


def register(linter):
    """required method to auto register this checker"""
    linter.register_checker(DocStringChecker(linter))

As I recall this system doesn't have great docs (that may have changed in the past year). This at least gives you something to start hacking on / really simple code in place of docs.

回答2:

I don't think it's validating against any PEPs, but Epydoc will check that all of the referenced parameters and objects in docstrmap to valid parameters and objects.