Style checker for sphinx (or other) rst documentation.
15ee57b572
When a check is for a rst file vs a plaintext file and is not interoperable this change allows that check to declare that it only knows how to scan certain files. It also fixes the max line checker to use a similar routine to differentiate between rst files and non rst files and uses a different routine based on this decision. Change-Id: I1e3e5f9f1631ed5babe2df17c987e8e872938a38 |
||
---|---|---|
doc/source | ||
doc8 | ||
.gitignore | ||
.gitreview | ||
CONTRIBUTING.rst | ||
HACKING.rst | ||
LICENSE | ||
MANIFEST.in | ||
pylintrc | ||
README.rst | ||
requirements.txt | ||
setup.cfg | ||
setup.py | ||
test-requirements.txt | ||
tox.ini |
Doc8
Doc8 is a opinionated style checker for sphinx (or other) rst documentation.
Features
- Ability to parse and validate rst files.
QuickStart
pip install doc8
To run doc8 just invoke it against any doc directory:
$ doc8 coolproject/docs
Usage
$ doc8 -h
usage: doc8 [-h] [--config path] [--allow-long-titles] [--ignore code]
[--ignore-path path] [--max-line-length int] [-e extension]
[path [path ...]]
Check documentation for simple style requirements.
What is checked:
- invalid rst format - D000
- lines should not be longer than 79 characters - D001
- exception: line with no whitespace except in the beginning
- exception: lines with http or https urls
- exception: literal blocks
- exception: rst target directives
- no trailing whitespace - D002
- no tabulation for indentation - D003
- no carriage returns (use unix newlines) - D004
positional arguments:
path path to scan for doc files (default: os.getcwd())
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 errors code/codes
--no-sphinx do not ignore sphinx specific false positives
--ignore-path path
ignore the given directory or file
--max-line-length int
maximum allowed line length (default: 79)
-e extension, --extension extension
check file extensions of the given type (default:
.rst, .txt)