Welcome To Docsweeper’s Documentation!#

Docsweeper is a linter for version controlled Python code bases that finds potentially outdated docstrings. Docsweeper interacts with the version control system to retrieve a full revision history of a given Python source file. For every code token in the file that has a docstring (see PEP 257), Docsweeper will analyze the version control history to determine:

  1. in which revision the docstring has last been changed, and

  2. how often the source code that is referenced by the docstring has been altered since that revision.

This can help you quickly find potentially outdated docstrings in your Python code base.

Docsweeper can be used as a stand-alone application or as a plugin for the Flake8 linter.

Which Version Control Systems Does Docsweeper Support?#

Docsweeper supports the following version control systems:

  1. Git v1.7.0 or newer, and

  2. Mercurial v5.2 or newer. This is the the first release of Mercurial with official support for Python 3.

Installation#

Docsweeper requires an installation of Python v3.7 or newer. It also requires the following additional packages:

Docsweeper is available on PyPI. Install the package with pip to take care of dependencies automatically:

$ pip install docsweeper

Usage#

Docsweeper can be used as a Flake8 plugin, from the command line, or directly from Python code.

Using Docsweeper As A Flake8 plugin#

Upon installation, Docsweeper will register itself automatically as a plugin for Flake8 if it is installed. See configuration instructions for instructions on how to configure the plugin.

Error/Violation Codes#

Docsweeper employs the following Flake8 error codes:

DOC100 Potentially Outdated Docstring#

The code of this token has changed more times than allowed since the docstring that references it has been updated.

The amount of allowed code changes until this violation triggers is determined by the --max_changes command line option or max_changes option in the Flake8 configuration file.

Invoking Docsweeper From Command Line#

A list of available version control system interfaces and their default executable locations is printed at the end of the command line help:

$ docsweeper -h

For example, to analyze the source file source.py in a git repository, run:

$ docsweeper --vcs-shim git source.py

If the default executable location for your version control system is not correct for your system, override it using --vcs-executable option or a configuration file:

$ docsweeper --vcs-shim git --vcs-executable /path/to/git source.py

Invoking Docsweeper From Python Code#

See Example Usage.

Configuration#

Configuration Of Docsweeper As A Flake8 Plugin#

The Flake8 plugin can be configured via a configuration section in the Flake8 configuration file or by passing specific command line options to the flake8 command.

Important

The Flake8 plugin is disabled by default. Add DOC100 to your enabled extensions in your Flake8 configuration to use it:

[flake8]
enable-extensions=DOC100

Plugin Configuration In The Flake8 Configuration File#

The following options are respected by Docsweeper if set by the user:

max_changesinteger

Amount of code changes that are allowed since the last docstring update before code violation DOC100 triggers.

Default value: 0

no_follow_rename

Follow version control history along renames of files.

Default value: false

vcsstring

Version control system that is used. Currently supported values are git and hg.

Default value: git

vcs_executablestring

Location of the version control system executable.

Default value: see the output of docsweeper -h

Plugin Configuration With Command Line Options#

The following command line options are available:

–max-changes MAX_CHANGESinteger

Maximum allowed changes of code since last docstring change before code violation DOC100 triggers.

–no-follow-rename :

Follow version control history along renames of files.

–vcs VCS_TYPEgit | hg

Choose the type of version control system.

–vcs-executable VCS_EXECUTABLEstring

Path of the version control system executable.

Configuration Of Docsweeper As A Standalone Application#

The stand-alone version of Docsweeper is configured independently of the Flake8 plugin via command line parameters or using a configuration file. Command line options always take precedence over values in a configuration file.

Configuration Via Command Line#

A full command line reference is available by running docsweeper -h.

Configuration Via File#

If Docsweeper is passed the command line option --config or -c followed by the path of a configuration file, it will try to load configuration values from this file. The following example shows all configuration sections and the options they support:

[docsweeper] :

Configuration section for general options.

vcsgit | hg

Choose the type of version control system.

Default value git

follow_renamebool

Follow version control history along renames of files.

Default value: true

[docsweeper.git] :

Configuration section for git.

executablestring

Path of the git executable.

Default value: see the output of docsweeper -h

[docsweeper.hg] :

Configuration section for Mercurial.

executablestring

Path of the Mercurial executable.

Default value: see the output of docsweeper -h

[docsweeper]
vcs = git
follow_rename = True

[docsweeper.git]
executable = /usr/bin/git

[docsweeper.hg]
executable = /usr/bin/hg

Further Information#

Indices and tables#