Sphinx（或其他）RST文档的风格检查器
项目描述
doc8
doc8 是一个针对 rst （支持纯文本基本样式）文档样式的有偏见的风格检查器。
快速入门
pip install doc8
要运行 doc8，只需将其应用于任何文档目录
$ doc8 cool-project/docs
用法
$ 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 文件用法
除了使用 CLI 选项外，以下文件也将被检查是否存在 [doc8] 部分，这些部分也可以提供相同的选项集。如果使用了 --config 路径 选项，则不会扫描当前工作目录和该配置路径，而是使用该配置路径。
$CWD/doc8.ini
$CWD/.config/doc8.ini
$CWD/tox.ini
$CWD/pep8.ini
$CWD/setup.cfg
$CWD/pyproject.toml
可以放置到这些文件中的示例部分
[doc8] ignore-path=/tmp/stuff,/tmp/other_stuff max-line-length=99 verbose=1 ignore-path-errors=/tmp/other_thing.rst;D001;D002
pyproject.toml 文件的示例
[tool.doc8] ignore = ["D001"] allow-long-titles = true
注意：选项名称与命令行选项相同（唯一的区别是 no-sphinx 选项，在配置文件中将变为 sphinx）。
选项冲突解决
当通过命令行和配置文件传递相同的选项时，将应用以下策略来解决这些类型的冲突。
选项 |
覆盖 |
合并 |
|---|---|---|
allow-long-titles |
是 |
否 |
ignore-path-errors |
否 |
是 |
default-extension |
是 |
否 |
extension |
否 |
是 |
ignore-path |
否 |
是 |
ignore |
否 |
是 |
max-line-length |
是 |
否 |
file-encoding |
是 |
否 |
sphinx |
是 |
否 |
注意：在上表中的配置文件选项，当指定为 overrides 时，将替换通过命令行提供的相同选项。当指定为 merges 时，则选项将与命令行选项合并（例如，通过成为一个包含通过命令行和通过配置传递的值的更大的列表或值集）。
API
还可以以编程方式使用 doc8。要从 Python 项目调用 doc8，使用
from doc8 import doc8 result = doc8(allow_long_titles=True, max_line_length=99)
返回的 result 将具有以下属性和方法
result.files_selected - 选定的文件数
result.files_ignored - 忽略的文件数
result.error_counts - dict 的 {check_name: error_count}
result.total_errors - 找到的错误总数
result.errors - (check_name, filename, line_num, code, message) 元组的列表
result.report() - 返回一个可读报告字符串
doc8 方法接受与可执行文件相同的参数。只需将连字符替换为下划线即可。
注意：以这种方式调用 doc8 不会写入 stdout，所以忽略 quiet 和 verbose 选项。
下载文件
下载适用于您平台的文件。如果您不确定选择哪一个，请了解有关安装包的更多信息。