x
/
doc8
Code Issues Proposed changes
Style checker for sphinx (or other) rst documentation.
87 Commits 1 Branch 12 Tags 632 KiB
Go to file
Joshua Harlow 478b87b106 Add a sphinx specific mode 
When doc8 scans rst files with sphinx specific roles
and references it is unable to determine what those roles
are and then complains that these false positives are
actual errors.

To avoid these types of false positives add a option that
can be provided when running on files that may contain these
types of errors to allow them to be skipped/ignored.

Change-Id: Ia6896617534f68e517d5996d53cf2de274507f56
 		2014-08-15 15:05:41 -07:00
doc/source Check documents for doc8 issues and fix one doc8 issue 2014-08-15 14:27:50 +02:00
doc8 Add a sphinx specific mode 2014-08-15 15:05:41 -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 Add a sphinx specific mode 2014-08-15 15:05:41 -07:00
pylintrc Add Pylint testenv environment 2014-08-15 14:32:30 +02:00
requirements.txt Make build environment workable 2014-08-01 16:18:40 +02: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 Merge "Add Pylint testenv environment" 2014-08-15 19:26:57 +00: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 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)