Sphinx开发人员指南

Abstract

本文档描述了Sphinx的开发过程，Sphinx是开发人员用来记录其他开发人员用于开发其他系统的系统的文档系统，这些系统也可以使用Sphinx进行记录。

Sphinx源代码使用Git进行管理，并托管在GitHub上。

git clone git://github.com/sphinx-doc/sphinx

社区

sphinx-users <sphinx-users@googlegroups.com>

用户支持的邮件列表。

sphinx-dev <sphinx-dev@googlegroups.com>

发展相关讨论的邮件列表。

#sphinx-doc on irc.freenode.net

IRC频道用于开发问题和用户支持。

错误报告和功能请求

如果您遇到了Sphinx的问题或者对新功能有所了解，请将其提交给GitHub上的 issue tracker 或在 sphinx-dev 邮件列表中进行讨论。

对于错误报告，请包括构建过程中产生的输出以及Sphinx遇到未处理异常后创建的日志文件。应在错误消息的末尾显示此文件的位置。

包含或提供所涉及的源文件的链接可以帮助我们解决问题。如果可能的话，尝试创建一个产生错误的最小项目，然后发布它。

为Sphinx做贡献

新贡献者向Sphinx提交代码的推荐方法是在GitHub上分割存储库，然后在提交更改后提交拉取请求。然后，在将请求合并到主存储库之前，需要由其中一个核心开发人员批准。

1. 检查未解决的问题或打开一个新问题，以围绕功能创意或错误开始讨论。

2. 如果您对某个问题或更改感到不安或不确定，请随时给 sphinx-dev 邮件列表发送电子邮件。

3. 在GitHub上使用 the repository 来开始对下一个 MAJOR 版本的 master 分支进行更改，或者对下一个MINOR版本进行 X.Y 分支(参见 Branch Model)。

4. 编写一个测试，显示错误已修复或该功能按预期工作。

5. 发送拉取请求并对维护者提出错误，直到它被合并并发布。 确保将自己添加到 AUTHORS 并将更改添加到 CHANGES 。

入门

这些是开始在Sphinx上开发所需的基本步骤。

1. 在GitHub上创建一个帐户。

2. 使用GitHub接口分叉主要的Sphinx存储库(sphinx-doc/sphinx)。

3. 将分叉的存储库克隆到您的计算机。

   git clone https://github.com/USERNAME/sphinx
   cd sphinx
   

4. 签出适当的分支。

   Sphinx采用语义版本2.0.0 (refs: https://semver.org/ ).

   对于保留API和功能的向后兼容性的更改，它们应该包含在下一个MINOR版本中，使用 X.Y 分支。:

   git checkout X.Y
   

   对于应该等到下一个MAJOR版本的不兼容或其他实质性更改，请使用 master 分支。

   对于紧急发布，必须从最新的发布标记分支新的PATCH分支(有关详细信息，请参阅`Branch Model`_)。

5. 设置虚拟环境。

   这对于单元测试来说不是必需的，这要归功于 tox ，但是如果你想在本地运行 sphinx-build 或者在没有 tox 的帮助下运行单元测试，这是必要的。:

   virtualenv ~/.venv
   . ~/.venv/bin/activate
   pip install -e .
   

6. 创建一个新的工作分支。选择您喜欢的任何名称。

   git checkout -b feature-xyz
   

7. 黑客，破解，破解。

   有关使用代码的提示，请参阅 Coding Guide.

8. 测试，测试，测试。

   测试最好通过 tox 来完成，它提供了许多目标，并允许针对多种不同的Python环境进行测试:

   • 列出所有可能的 targets:

     tox -av
     

   • 为特定的Python版本运行单元测试，例如 3.6:

     tox -e py36
     

   • 要运行特定Python版本的单元测试并启用弃用警告，以便它们显示在测试输出中:

     PYTHONWARNINGS=all tox -e py36
     

   • 运行代码样式和类型 checks:

     tox -e mypy
     tox -e flake8
     

   • pytest 的参数可以通过 tox 传递，例如为了进行特定的测试:

     tox -e py36 tests/test_module.py::test_new_feature
     

   • 建立 documentation:

     tox -e docs
     

   • 以多种方式构建文档 formats:

     tox -e docs -- -b html,latexpdf
     

   • 要使用 Karma 运行JavaScript测试，请执行以下命令(需要 Node.js):

     npm install
     npm run test
     

   您还可以通过在本地环境中安装依赖项来进行测试。

   pip install .[test]
   

   必要时，新的单元测试应包含在 tests 目录中:

   • 对于错误修复，首先添加一个在没有更改的情况下失败的测试，并在应用后通过。

   • 如果可能的话，需要将 sphinx-build 运行的测试集成到现有测试模块中。 对于 @with_app 然后 build_all 进行一些断言的新测试并不好，因为 测试套件运行时间不应超过一分钟 。

9. 如果修复或功能不重要(小文档更新，拼写错误修复)，请添加一个项目符号 CHANGES 。 然后提交:

   git commit -m '#42: Add useful new feature that does this.'
   

   GitHub识别可用于自动更新问题跟踪器的某些短语。

   例如:

   git commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
   

   会关闭第42期。

10. 将分支中的更改推送到GitHub上的分叉存储库。

    git push origin feature-xyz
    

11. 从您的分支机构向相应的分支机构提交拉取请求(master 或 X.Y)。

12. 等待核心开发人员审核您的更改。

核心开发人员

Sphinx的核心开发人员具有对主存储库的写访问权。他们可以提交更改，接受/拒绝拉取请求以及管理问题跟踪器上的项目。

您不需要成为核心开发人员或具有写入权限以参与Sphinx的开发。您可以从分叉存储库提交补丁或创建拉取请求，并让核心开发人员为您添加更改。

以下是核心开发人员的一些一般准则:

• 应将可疑或广泛的更改作为拉取请求提交，而不是直接提交到主存储库. 拉取请求应在合并之前由其他核心开发人员审核。

• 可以直接提交简单的更改，但一定要保持存储库处于良好的工作状态，并且在推送更改之前所有测试都会通过。

• 在提交由其他人编写的代码时，请在提交消息和任何相关的 CHANGES 条目中归因于原作者。

区域设置更新

Sphinx中进入构建的消息部分被转换为多个语言环境。翻译保存为从主模板 sphinx/locale/sphinx.pot 翻译的 gettext .po 文件。

Sphinx使用 Babel 来提取消息并维护目录文件。 它集成在 setup.py 中:

• 使用 python setup.py extract_messages 来更新 .pot 模板。

• 使用 python setup.py update_catalog 使用模板文件中的当前消息更新 sphinx/locale/*/LC_MESSAGES 中的所有现有语言目录。

• 使用 python setup.py compile_catalog 将 .po 文件编译为二进制 .mo 文件和 .js 文件。

当提交更新的 .po 文件时，运行 compile_catalog 以提交源和已编译的目录。

提交新的语言环境时，添加一个带有ISO 639-1语言标识符的新目录，并在其中放置 sphinx.po 。不要忘记在 doc/config.rst 中更新 language 的可能值。

Sphinx核心消息也可以在 Transifex 上翻译。在Python包 “transifex_client” 中存在一个名为 tx 的客户端工具，它可用于从Transifex中以 .po 格式提取翻译。 为此，请转到 sphinx/locale 然后运行 tx pull -f -l LANG ，其中LANG是现有的语言标识符。 最好在之后运行 python setup.py update_catalog 以确保 .po 文件具有规范的Babel格式。

编码指南

• 尝试使用与项目其余部分相同的代码样式。 有关更多信息，请参阅 Pocoo Styleguide 。

• 对于非平凡的更改，请更新 CHANGES 文件。如果您的更改改变了现有行为，请记录下来。

• 应记录新功能。在适当的地方包括示例和用例。 如果可能，请包括生成的输出中显示的样本。

• 添加新的配置变量时，请务必记录并更新 sphinx/cmd/quickstart.py ，如果它足够重要的话。

• 添加适当的单元测试。

调试技巧

• 如果通过运行命令 make clean 或使用 sphinx-build -E 选项在代码中进行更改，则在构建文档之前删除构建缓存。

• 使用 sphinx-build -P 选项在异常上运行 pdb 。

• 使用 node.pformat() 和 node.asdom().toxml() 生成文档结构的可打印表示。

• 将配置变量 keep_warnings 设置为 True ，以便在生成的输出中显示警告。

• 将配置变量 nitpicky 设置为 True ，以便Sphinx会抱怨没有已知目标的引用。

• 在 Docutils配置文件中设置调试选项.

• sphinx/search/*.py (除了 en.py)中的JavaScript词干算法是由这个 修改过的snowballcode生成器 生成的。 生成的 JSX 文件位于 此存储库 。您可以使用以下命令获取生成的JavaScript文件:

  npm install
  node_modules/.bin/grunt build # -> dest/*.global.js
  

分支模型

Sphinx项目使用以下分支进行开发，符合Semantic Versioning 2.0.0 (refs: https://semver.org/ ).

master

开发MAJOR版本。允许所有更改，包括不兼容的行为和公共API更新。

X.Y

其中 X.Y 是 MAJOR.MINOR 。用于维持当前的MINOR版本。如果更改保留了API和功能的向后兼容性，则允许所有更改。

目前仅保留最新的 MAJOR.MINOR 分支。当一个新的MAJOR版本发布时，旧的 MAJOR.MINOR 分支将被删除并被等效标记取代。

X.Y.Z

其中 X.Y.Z 是 MAJOR.MINOR.PATCH 。只允许向后兼容的错误修复。在Sphinx项目中，PATCH版本用于紧急错误修复。

当需要紧急释放时，MAJOR.MINOR.PATCH 分支将从 v 前缀释放标记(例如，从2.3版本分支的make 2.3.1)分支出来。当发布新的PATCH版本时，分支将被删除并替换为等效标记(例如v2.3.1)。

弃用某个功能

有几个原因导致Sphinx中的代码可能被弃用:

• 如果某项功能以向后兼容的方式进行了改进或修改，则旧功能或行为将被弃用。

• 有时，Sphinx将包含一个Python库的后端，该库未包含在Sphinx目前支持的Python版本中。当Sphinx不再需要支持不包含该库的旧版Python时，将在Sphinx中弃用该库。

正如 弃用政策 所描述的，Sphinx的第一个版本弃用了一个特性(AB)应该引发一个 RemovedInSphinxXXWarning (其中 XX 是Sphinx版本的特征将被删除)调用已弃用的功能时。假设我们具有良好的测试覆盖率，则在运行启用了警告的测试套件时，这些警告会转换为错误:

pytest -Wall

因此，在添加 RemovedInSphinxXXWarning 时，您需要消除或消除运行测试时生成的任何警告。

弃用政策

MAJOR 和 MINOR版本可能会弃用先前版本中的某些功能。 如果在版本A.x中不推荐使用某个功能，它将继续适用于所有A.x.x版本(适用于所有版本的x)。 它将继续在所有B.x.x版本中工作，但会引发弃用警告。 不推荐使用的功能将在C.0.0中删除。这意味着已弃用的功能至少在2个MAJOR版本中有效。

所以，例如，如果我们决定在Sphinx 2.x中开始弃用函数:

• Sphinx 2.x将包含一个向后兼容的函数副本，它将引发一个 RemovedInSphinx40Warning 。

• Sphinx 3.x 仍将包含向后兼容的副本。

• Sphinx 4.0 将彻底删除该功能。

默认情况下会显示警告。您可以使用以下命令关闭这些警告的显示:

• PYTHONWARNINGS= make html (Linux/Mac)

• export PYTHONWARNINGS= and do make html (Linux/Mac)

• set PYTHONWARNINGS= and do make html (Windows)

单元测试

Sphinx已经过pytest runner的测试。 Sphinx开发人员使用pytest表示法编写单元测试。 用于测试的实用函数和pytest夹具在 sphinx.testing 中提供。 如果您是Sphinx扩展的开发人员，可以使用pytest编写单元测试。 这时， sphinx.testing 将帮助您进行测试。

如何使用 sphinx.testing 提供的pytest灯具？您可以在测试模块中使用 'sphinx.testing.fixtures' 或像这样的 conftest.py 文件:

pytest_plugins = 'sphinx.testing.fixtures'

如果你想了解更详细的用法，请参考 tests 目录下的 tests/conftest.py 和其他 test_*.py 文件。

注解

在Sphinx - 1.5.2之前，Sphinx正在进行鼻子测试。

1.6 新版功能: sphinx.testing 作为实验.

1.8 新版功能: Sphinx还运行JavaScript测试。