Welcome To Docsweeper’s Documentation!#

Docsweeper is a linter for version controlled Python code bases that finds potentially outdated docstrings in your source files. For every code token in the file that has a docstring (see PEP 257), Docsweeper will interact with your Git or Mercurial version control system 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.

Used as a stand-alone application or as a plugin for the Flake8 linter, Docsweeper can be integrated into your code check-in or linting process easily and help you quickly determine which docstrings potentially contain obsolete information.

Compatibility#

Docsweeper supports Linux, Mac, and Windows platforms that are compatible with Python 3.7 or newer. In addition to a working Python installation, you will also need at least one of the version control systems you intend to use Docsweeper with:

  1. Git v1.7.0 or newer, and/or

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

Installation#

In addition to a working Python v3.7+ environment, the following additional packages are required as well:

Docsweeper is available on PyPI. Install it 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 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 git --vcs-executable /path/to/git source.py

Full Command Line Reference#

Note

This command line reference is also available by running docsweeper -h.

Usage: docsweeper [OPTIONS] FILE...

Analyze FILE or multiple FILEs for outdated docstrings.

Options:
--vcs VCS

Note

This command line option was introduced in v1.2.0.

History of FILEs will be retrieved using the version control system VCS.

Supported values for VCS: git | hg

Default value: git

-e, --vcs-executable PATH

the version control executable located at PATH will be used during analysis.

--no-follow-rename

Do not follow renames of files.

-c, --config PATH

Load a Docsweeper configuration file located at PATH.

-v, --verbose

Set verbose mode.

-d, --debug

Set debugging mode. Lots of messages.

-V, --version

Show version information.

--vcs-shim SHIM

Caution

This command line option is DEPRECATED since v1.2.0! Use option --vcs instead.

History of FILEs will be retrieved using the version control system SHIM.

Supported values for SHIM: git|hg

Default value: git

-h, --help

Show command line reference.

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 docsweeper to your enabled extensions in your Flake8 configuration to use it:

[flake8]
enable-extensions=docsweeper

Caution

Deprecation notice: Before Docsniffer v1.2.5, the option string to enable Docsweeper erroneously was DOC100 instead of docsweeper. This is kept for compatibility reasons, but will be removed in Docsniffer v2.0.0.

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_renametrue | false

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_CHANGES

Code violation DOC100 triggers when more than MAX_CHANGES changes to the source code have been made since the last docstring change.

--no-follow-rename

Follow version control history along renames of files.

--vcs VCS_TYPE

VCS_TYPE is the type of version control system used.

Allowed values: git|hg

--vcs-executable VCS_EXECUTABLE

The version control system located at VCS_EXECUTABLE will be used.

Using Docsweeper As A Standalone Application#

The stand-alone version of Docsweeper can be 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 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_renametrue | false

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#