flake8-rst-docstrings 0.3.0

简介

这是一个MIT许可的flake8插件，用于验证Python文档字符串标记为reStructuredText (RST)，使用Python库docutils。它可以从Python包索引（PyPI）安装。

此插件在很大程度上基于pydocstyle（也是MIT许可），它有一个名为flake8-docstrings的flake8插件，请参阅

• https://github.com/PyCQA/pydocstyle

• https://github.com/PyCQA/flake8-docstrings

reStructuredText (RST)验证是通过调用docutils并通过Todd Wolfson的restructuredtext-lint代码实现的

• http://docutils.sourceforge.net/

• https://github.com/twolfson/restructuredtext-lint

我建议您也安装相关的 flake8-docstrings 插件（链接），该插件将 pydocstyle 检查功能集成到 flake8 中。这包括检查缺失的文档字符串和其他来自 PEP 257 文档字符串约定 的建议。

您还可能希望安装相关的 flake8 插件 flake8-rst，它可以检查您的 *.rst 文件中 Python 代码的 doctest 格式片段或您的 *.py 文件中的文档字符串。

flake8 验证代码

flake8 的早期版本假设验证代码以单个字符前缀开头，这在插件生态系统中导致冲突。自 v3.0 版本以来，flake8 支持更长的前缀，因此该插件使用 RST 作为其前缀。

我们内部使用 docutils 进行 RST 验证，这在 PEP258 中有所说明

• Level-0，“DEBUG”：内部报告问题。对处理没有影响。Level-0 系统消息与其他消息分开处理。

• Level-1，“INFO”：可以忽略的小问题。对处理影响很小或没有影响。通常不报告 Level-1 系统消息。

• Level-2，“WARNING”：应该解决的问题。如果忽略，输出可能会有一些小问题。通常报告 Level-2 系统消息，但不会停止处理

• Level-3，“ERROR”：应该解决的问题的主要问题。如果忽略，输出将包含不可预测的错误。通常报告 Level-3 系统消息，但不会停止处理

• Level-4，“SEVERE”：必须解决的问题的严重错误。通常将 Level-4 系统消息转换为异常以停止处理。如果忽略，输出将包含严重错误。

docutils 的“DEBUG”级别消息不会报告，并且插件当前忽略“INFO”级别消息。

在每个类别中，单个消息映射到 flake8 代码，使用级别的 100 倍。例如，验证代码 RST4## 是 RST 验证的严重或关键错误，RST3## 是主要错误，RST2## 是警告，而目前尚未使用，RST1## 将仅是信息。

警告代码

主要错误代码

严重或关键错误代码

以99结尾的代码，例如RST499，表示一个之前未见过的验证错误，我们尚未为其分配唯一的验证代码，在本例中为RST4##。如果您看到这些代码之一，请在我们的GitHub问题跟踪器上报告，最好提供一个我们可以用于测试的示例。

以RST9##开头的代码表示在解析Python文件以提取文档字符串或在处理内容时出现问题。

安装和使用

现在需要Python 3.7或更高版本。早期版本支持Python 2.7，如果需要请使用v0.0.14。

我们建议使用pip安装插件，它处理依赖项。

$ pip install flake8-rst-docstrings

或者，如果您使用Anaconda打包系统，以下命令将安装插件及其依赖项

$ conda install -c conda-forge flake8-rst-docstrings

开发者可以从git仓库安装插件，包括可选依赖项

$ pip install -e .[develop]

当使用flake8时，新验证器应自动包括在内，它可能现在会报告以RST开头（如上所述）的附加验证代码。例如

$ flake8 example.py

您可以使用以下命令仅显示RST代码

$ flake8 --select RST example.py

同样，您可以将特定的RST验证代码添加到flake8配置文件的select或ignore列表中。

注意，除了单独的RST前缀外，您还可以使用部分代码，如RST2，表示RST200、RST201、……等等。

通常flake8违规是对特定的行和列。不幸的是，docutils只提供行号，偶尔这仅指向段落的开始，而不是问题所在的精确行。

配置

我们假设您熟悉flake8配置。

如果您使用Sphinx或其他reStructuredText扩展，您将想要定义您使用的任何附加指令或角色，以避免虚假的RST303、RST304和RST305违规。您可能还需要在Sphinx指令中使用参数时忽略RST307。

如果您愿意，可以在命令行中设置这些

$ flake8 --rst-roles class,func,ref --rst-directives envvar,exception ...

我们建议将此设置记录在您的flake8配置中，例如在您的.flake8、setup.cfg或tox.ini文件中，例如

[flake8]
rst-roles =
    class,
    func,
    ref,
rst-directives =
    envvar,
    exception,
rst-substitutions =
    version,
extend-ignore =
    RST307,
    # ...

请注意，flake8允许在多行上拆分逗号分隔的列表，并允许包括哈希注释行。

如果您使用Google Python Style，您有时会从这个插件中获得不想要的警告，尤其是在参数描述中——因为它不使用严格的RST。因此，我们目前建议忽略一些违规代码。

[flake8]
extend-ignore =
    # Google Python style is not RST until after processed by Napoleon
    # See https://github.com/peterjc/flake8-rst-docstrings/issues/17
    RST201,RST203,RST301,

版本历史

开发者

此插件位于 GitHub 上 https://github.com/peterjc/flake8-rst-docstrings

一旦在本地和 TravisCI 上测试，则发布新版本。

$ git tag vX.Y.Z
$ python -m build
$ git push origin master --tags
$ twine upload dist/flake8?rst?docstrings-X.Y.Z*

PyPI 上传应触发自动拉取请求，更新 flake8-rst-docstrings conda-forge 脚本。