Sphinx Lint

Sphinx Lint 基于 CPython 的 rstlint.py。

什么是 Sphinx Lint，它不是什么？

Sphinx Lint 应该

• 运行得相对快速，以便在编辑器中作为代码检查器使用。
• 能够处理单个文件。
• 不产生任何误报（可能是一个乌托邦式的目标，但让我们试试）。
• 不要花费太多精力去寻找 sphinx-build 已经找到（或可以轻松找到）的错误。
• 专注于寻找 sphinx-build 无法看到（或不显示）的错误。

使用 Sphinx Lint

以下是命令行中一些 Sphinx Lint 的示例调用

sphinx-lint           # check all dirs and files
sphinx-lint file.rst  # check a single file
sphinx-lint docs      # check a directory
sphinx-lint -i venv   # ignore a file/directory
sphinx-lint -h        # for more options

Sphinx Lint 还可以通过 pre-commit 使用。我们推荐使用以下配置

  - repo: https://github.com/sphinx-contrib/sphinx-lint
    rev: LATEST_SPHINXLINT_RELEASE_TAG
    hooks:
      - id: sphinx-lint

已知问题

目前 Sphinx Lint 无法与表格一起工作，无法理解表格中 linesplit 的作用，例如

   +-----------------------------------------+-----------------------------+---------------+
   | Method                                  | Checks that                 | New in        |
   +=========================================+=============================+===============+
   | :meth:`assertEqual(a, b)                | ``a == b``                  |               |
   | <TestCase.assertEqual>`                 |                             |               |
   +-----------------------------------------+-----------------------------+---------------+

由于 Sphinx Lint 是逐行工作的，它不可避免地认为 :meth: 角色没有被正确关闭。

为了避免误报，如果在表格中，将跳过一些规则。

贡献

快速测试某种语法是否从纯 reStructuredText 观点来看是有效的，可以通过使用 docutils 的 pseudoxml 编写器，例如

$ docutils --writer=pseudoxml tests/fixtures/xpass/role-in-code-sample.rst
<document source="tests/fixtures/xpass/role-in-code-sample.rst">
    <paragraph>
        Found in the pandas documentation, this is valid:
    <bullet_list bullet="*">
        <list_item>
            <paragraph>
                A pandas class (in the form
                <literal>
                    :class:`pandas.Series`
                )
        <list_item>
            <paragraph>
                A pandas method (in the form
                <literal>
                    :meth:`pandas.Series.sum`
                )
        <list_item>
            <paragraph>
                A pandas function (in the form
                <literal>
                    :func:`pandas.to_datetime`
                )
    <paragraph>
        it's documenting roles using code samples (double backticks).

发布

1. 确保 CI 测试通过，并且可选地通过运行 "friends projects" 本地双重检查

   sh download-more-tests.sh
   python -m pytest
   

2. 转到 发布页面

3. 点击 "创建新发布"

4. 点击 "选择标签"

5. 输入下一个 vX.Y.Z 版本并选择 "在发布时创建新标签：VX.Y.Z"

6. 留空 "发布标题"（它将被自动填写）

7. 点击 "生成发布说明"并按需修改

8. 点击 "发布发布"

9. 检查带有标签的 GitHub Actions 构建 是否已 部署到 PyPI

许可证

由于此脚本位于 CPython 存储库中，其许可证为 Python 软件基金会许可证版本 2，有关完整版本，请参阅 LICENSE 文件。