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:
in which revision the docstring has last been changed, and
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:
Git v1.7.0 or newer, and/or
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:
click v8.1.0 or newer.
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_changes
integerAmount of code changes that are allowed since the last docstring update before code violation DOC100 triggers.
Default value:
0
no_follow_rename
true
|false
Follow version control history along renames of files.
Default value:
false
vcs
stringVersion control system that is used. Currently supported values are
git
andhg
.Default value:
git
vcs_executable
stringLocation 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.
- vcs
git
|hg
Choose the type of version control system.
Default value
git
- follow_rename
true
|false
Follow version control history along renames of files.
Default value:
true
- vcs
- [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