Style checker for Sphinx (or other) RST documentation
Project description
Doc8 is a opinionated style checker for rst (with basic support for plain text) styles of documentation.
QuickStart
pip install doc8
To run doc8 just invoke it against any doc directory:
$ doc8 coolproject/docs
Usage
Command line usage
$ doc8 -h
usage: doc8 [-h] [--config path] [--allow-long-titles] [--ignore code]
[--no-sphinx] [--ignore-path path] [--default-extension extension]
[--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
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 (globs are
supported)
--default-extension extension
Default file extension to use when a file is found
without a file extension.
--max-line-length int
maximum allowed line length (default: 79)
-e extension, --extension extension
check file extensions of the given type (default:
.rst, .txt)
-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:
[doc8] ignore_path=/tmp/stuff,/tmp/other_stuff max_line_length=99 verbose=1
Note: The option names are the same as the command line ones but instead of dashes underscores are used instead (with the only variation of this being the no-sphinx option which from configuration file will be sphinx instead).
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 |
default-extension |
Yes |
No |
extension |
No |
Yes |
ignore-path |
No |
Yes |
ignore |
No |
Yes |
max-line-length |
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).
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file doc8-0.4.3.tar.gz.
File metadata
- Download URL: doc8-0.4.3.tar.gz
- Upload date:
- Size: 20.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | a65444a0601259e64dbd71b7d65add2b11055486e2c870d117853f5e2b7a0794 |
|
| MD5 | fb91addd76796cb096a85801ab2a3f95 |
|
| BLAKE2b-256 | 6c14c2f717092c9f962b705352c6f0f3b8d4b7b9b573cb8608ac9ab5e273bfb7 |
Provenance
File details
Details for the file doc8-0.4.3-py2.py3-none-any.whl.
File metadata
- Download URL: doc8-0.4.3-py2.py3-none-any.whl
- Upload date:
- Size: 17.5 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | cfc011a66366a9c2e5b214b9a61fb3207d46fee390e18c912106949b38dd6950 |
|
| MD5 | 1e3c349cf7a28c747563c06561e34428 |
|
| BLAKE2b-256 | 6c3340a229fea5c6211708f26d12b07309c7c9e67d0b8350a0a6c70e709045ef |
