Package: doc8
doc8doc8is anopinionatedstyle checker forrst(with basic support for
plain text) styles of documentation.Quick startpip install doc8To rundoc8, just invoke it against any documentation directory:$ doc8 cool-project/docsUsage$ doc8  -h

usage: doc8 [-h] [--config path] [--allow-long-titles] [--ignore code]
            [--no-sphinx] [--ignore-path path] [--ignore-path-errors path]
            [--default-extension extension] [--file-encoding encoding]
            [--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
    - no newline at end of file - D005

positional arguments:
  path                  Path to scan for doc files (default: current
                        directory).

optional arguments:
  -h, --help            show this help message and exit
  --config path         user config file location (default: .config/doc8.ini, doc8.ini, tox.ini,
                        pep8.ini, setup.cfg).
  --allow-long-titles   allow long section titles (default: false).
  --ignore code         ignore the given error code(s).
  --no-sphinx           do not ignore sphinx specific false positives.
  --ignore-path path    ignore the given directory or file (globs are
                        supported).
  --ignore-path-errors path
                        ignore the given specific errors in the provided file.
  --default-extension extension
                        default file extension to use when a file is found
                        without a file extension.
  --file-encoding encoding
                        set input files text encoding
  --max-line-length int
                        maximum allowed line length (default: 79).
  -e extension, --extension extension
                        check file extensions of the given type (default:
                        .rst, .txt).
  -q, --quiet           only print violations
  -v, --verbose         run in verbose mode.
  --version             show the version and exit.INI file usageInstead of using the CLI for options the following files will also be examined
for[doc8]sections that can also provide the same set of options. If
the--configpathoption is used, these files willnotbe scanned for
the current working directory and that configuration path will be used
instead.$CWD/doc8.ini$CWD/.config/doc8.ini$CWD/tox.ini$CWD/pep8.ini$CWD/setup.cfg$CWD/pyproject.tomlAn 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
ignore-path-errors=/tmp/other_thing.rst;D001;D002Note:The option names are the same as the command line ones (with the
only variation of this being theno-sphinxoption which from the
configuration file will besphinxinstead).Option conflict resolutionWhen 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.OptionOverridesMergesallow-long-titlesYesNoignore-path-errorsNoYesdefault-extensionYesNoextensionNoYesignore-pathNoYesignoreNoYesmax-line-lengthYesNofile-encodingYesNosphinxYesNoNote:In the above table the configuration file option when specified asoverrideswill replace the same option given via the command line. Whenmergesis 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 lineandthe values passed via
configuration).APIIt is also possible to usedoc8programmatically. To calldoc8from a
Python project, use:from doc8 import doc8

result = doc8(allow_long_titles=True, max_line_length=99)The returnedresultwill have the following attributes and methods:result.files_selected- number of files selectedresult.files_ignored- number of files ignoredresult.error_counts-dictof{check_name: error_count}result.total_errors- total number of errors foundresult.errors- list of(check_name, filename, line_num, code, message)tuplesresult.report()- returns a human-readable report as a stringThedoc8method accepts the same arguments as the executable. Simply
replace hyphens with underscores.Note:Callingdoc8in this way will not write to stdout, so thequietandverboseoptions are ignored.