Skip to content
Style checker for sphinx (or other) rst documentation.
Branch: master
Clone or download
ssbarnea Merge pull request #17 from radiac/feature/python-api
Add support for running directly from Python
Latest commit 4b57d2e Aug 25, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc Refactor to support direct invocation from python Aug 23, 2019
doc8 Refactor to support direct invocation from python Aug 23, 2019
.gitignore gitignore: Ignore pbr generated metadata Jul 24, 2019
.gitreview Update .gitreview for new namespace Oct 17, 2015
.pre-commit-hooks.yaml Fix formatting of pre-commit-hooks.yaml Jul 30, 2019
.travis.yml Enable pre-commit Aug 11, 2019
CONTRIBUTING.rst CONTRIBUTING: Update after move to GitHub Jul 24, 2019
LICENSE Enable pre-commit Aug 11, 2019
README.rst Refactor to support direct invocation from python Aug 23, 2019
requirements.txt Add Pygments to the requirements list Jan 24, 2018
setup.cfg Adopt python black Aug 12, 2019 Adopt python black Aug 12, 2019
test-requirements.txt Add tests for command line invocation Aug 23, 2019
tox.ini Adopt python black Aug 12, 2019


PyPI - License

GitHub last commit


Doc8 is an opinionated style checker for rst (with basic support for plain text) styles of documentation.


pip install doc8

To run doc8 just invoke it against any doc directory:

$ doc8 coolproject/docs


Command line usage

$ doc8  -h

usage: doc8 [-h] [--config path] [--allow-long-titles] [--ignore code]
            [--no-sphinx] [--ignore-path path] [--ignore-path-errors path]
            [--default-extension extension] [--file-encoding encoding]
            [--max-line-length int] [-e extension] [-v] [--version]
            [path [path ...]]

Check documentation for simple style requirements.

What is checked:
    - invalid rst format - D000
    - lines should not be longer than 79 characters - D001
      - RST exception: line with no whitespace except in the beginning
      - RST exception: lines with http or https urls
      - RST exception: literal blocks
      - RST exception: rst target directives
    - no trailing whitespace - D002
    - no tabulation for indentation - D003
    - no carriage returns (use unix newlines) - D004
    - no newline at end of file - D005

positional arguments:
  path                  Path to scan for doc files (default: current

optional arguments:
  -h, --help            show this help message and exit
  --config path         user config file location (default: doc8.ini, tox.ini,
                        pep8.ini, setup.cfg).
  --allow-long-titles   allow long section titles (default: false).
  --ignore code         ignore the given error code(s).
  --no-sphinx           do not ignore sphinx specific false positives.
  --ignore-path path    ignore the given directory or file (globs are
  --ignore-path-errors path
                        ignore the given specific errors in the provided file.
  --default-extension extension
                        default file extension to use when a file is found
                        without a file extension.
  --file-encoding encoding
                        override encoding to use when attempting to determine
                        an input files text encoding (providing this avoids
                        using `chardet` to automatically detect encoding/s)
  --max-line-length int
                        maximum allowed line length (default: 79).
  -e extension, --extension extension
                        check file extensions of the given type (default:
                        .rst, .txt).
  -q, --quiet           only print violations
  -v, --verbose         run in verbose mode.
  --version             show the version and exit.

Ini file usage

Instead of using the CLI for options the following files will also be examined for [doc8] sections that can also provided the same set of options. If the --config path option is used these files will not be scanned for the current working directory and that configuration path will be used instead.

  • $CWD/doc8.ini
  • $CWD/tox.ini
  • $CWD/pep8.ini
  • $CWD/setup.cfg

An example section that can be placed into one of these files:



Note: The option names are the same as the command line ones (with the only variation of this being the no-sphinx option which from configuration file will be sphinx instead).

Python Usage

To call doc8 from a Python project:

from doc8 import doc8

result = doc8(allow_long_titles=True, max_line_length=99)

The returned result will have the following attributes and methods:

  • result.files_selected - number of files selected
  • result.files_ignored - number of files ignored
  • result.error_counts - dict of {check_name: error_count}
  • result.total_errors - total number of errors found
  • result.errors - list of (check_name, filename, line_num, code, message) tuples
  • - returns a human-readable report as a string

Note that calling doc8 in this way will not write to stdout, so the quiet and verbose options are ignored.

Option conflict resolution

When the same option is passed on the command line and also via configuration files the following strategies are applied to resolve these types of conflicts.

Option Overrides Merges
allow-long-titles Yes No
ignore-path-errors No Yes
default-extension Yes No
extension No Yes
ignore-path No Yes
ignore No Yes
max-line-length Yes No
file-encoding Yes No
sphinx Yes No

Note: In the above table the configuration file option when specified as overrides will replace the same option given via the command line. When merges is stated then the option will be combined with the command line option (for example by becoming a larger list or set of values that contains the values passed on the command line and the values passed via configuration).

You can’t perform that action at this time.