Style checker for sphinx (or other) rst documentation.
Go to file
Joshua Harlow a16a84e37b Just remove the features sub-section
The main section already provides a basic overview of what
doc8 can do so it seems not so useful to duplicate that
information in a features sub-section as well.

Change-Id: I8f2215b030e2babcb28d4871239dfa926fec8f69
2014-09-05 17:58:58 +00:00
doc/source Check documents for doc8 issues and fix one doc8 issue 2014-08-15 14:27:50 +02:00
doc8 Log that the check does not understand the extension when verbose 2014-09-04 16:18:29 -07:00
.gitignore Initial commit 2014-05-17 18:46:57 -07:00
.gitreview Add .gitreview file 2014-05-29 11:24:06 +04:00
CONTRIBUTING.rst Add a few files from the openstack cookiecutter template 2014-05-19 10:04:21 -07:00
HACKING.rst Add a few files from the openstack cookiecutter template 2014-05-19 10:04:21 -07:00
LICENSE Initial commit 2014-05-17 18:46:57 -07:00
MANIFEST.in Add a few files from the openstack cookiecutter template 2014-05-19 10:04:21 -07:00
README.rst Just remove the features sub-section 2014-09-05 17:58:58 +00:00
pylintrc Add Pylint testenv environment 2014-08-15 14:32:30 +02:00
requirements.txt Detect the encoding using chardet 2014-08-22 22:04:36 -07:00
setup.cfg Released 0.3.5 2014-08-15 12:31:26 -07:00
setup.py Make build environment workable 2014-08-01 16:18:40 +02:00
test-requirements.txt Add basic check test cases 2014-08-28 17:37:35 -07:00
tox.ini Merge "Add Pylint testenv environment" 2014-08-15 19:26:57 +00:00

README.rst

Doc8

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] [--max-line-length int]
            [-e extension] [-v]
            [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 (globs are
                        supported)
  --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

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
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).