x
/
doc8
Code Issues Proposed changes
Style checker for sphinx (or other) rst documentation.
98 Commits 1 Branch 12 Tags 632 KiB
Go to file
Joshua Harlow 15ee57b572 Allow checks to provide a extension matcher 
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
 		2014-09-03 15:19:21 -07:00
doc/source Check documents for doc8 issues and fix one doc8 issue 2014-08-15 14:27:50 +02:00
doc8 Allow checks to provide a extension matcher 2014-09-03 15:19:21 -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 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 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)