x
/
doc8
Code Issues Proposed changes
Style checker for sphinx (or other) rst documentation.
72 Commits 1 Branch 12 Tags 632 KiB
Go to file
Joshua Harlow 8b4a229d93 Use restructuredtext-lint instead of duplication 
Now that the restructuredtext-lint project has fixed
its code we can remove our temporary copy of the logic
that library was providing to catch errors and warning that
are emitted when the rst structure is invalid.

Change-Id: I2fadde86ff0b2c8fbb6c828535da19e097f1894e
 		2014-06-25 10:39:55 -07:00
doc8 Use restructuredtext-lint instead of duplication 2014-06-25 10:39:55 -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 the new D000 to the rst file 2014-05-29 15:45:32 -07:00
setup.cfg Fixed a typo 2014-05-17 21:27:26 -07:00
setup.py Use restructuredtext-lint instead of duplication 2014-06-25 10:39:55 -07: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]
            [--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
  --max-line-length int
                        maximum allowed line length (default: 79)
  -e extension, --extension extension
                        check file extensions of the given type (default:
                        .rst, .txt)