RST Documentation Style Checker

2.0.0 · active · verified Sun Apr 12

doc8 is an opinionated style checker for reStructuredText (RST) based documentation, including Sphinx-compatible projects. It helps enforce style guidelines for `.rst` and plain text files. The library is currently at version 2.0.0, with a release cadence that addresses Python compatibility, bugfixes, and minor enhancements.

Warnings

breaking Version 2.0.0 and newer explicitly require Python 3.10 or higher. Users on older Python versions (e.g., 3.9 or below) must upgrade their Python environment to use the latest doc8.
Fix: Upgrade your Python environment to 3.10 or newer. For older Python versions, use doc8 < 2.0.0, e.g., `pip install 'doc8<2.0.0'`.
breaking Support for Python 3.7 was removed in v1.1.1. Further, Python 3.6 support was dropped in v1.0.0, and Python 2.7/3.5 support in v0.9.0.
Fix: Ensure your project's Python version meets the minimum requirements for the doc8 version you intend to use.
gotcha Configuration files have evolved. While `setup.cfg`, `doc8.ini`, `tox.ini`, and `.config/doc8.ini` are supported, `pyproject.toml` is the modern and preferred method for configuration. Ensure your configuration is correctly placed under a `[tool.doc8]` section in `pyproject.toml`.
Fix: Migrate your configuration to `pyproject.toml` for future compatibility. Example configuration structures can be found in the official documentation.
gotcha The `chardet` based input encoding detection was removed in v0.9.0, meaning `doc8` no longer attempts to automatically detect file encodings.
Fix: Explicitly set the file encoding using the `--file-encoding` option if your documentation files are not UTF-8.

Install

pip install doc8 Install stable version

Imports

doc8
```
from doc8 import doc8
```
Can be used programmatically by importing the main function.

Quickstart

Run doc8 against a directory containing your reStructuredText documentation to check for style violations.

pip install doc8
doc8 path/to/your/docs

view raw JSON →