贡献

本项目遵循 Read the Docs 的 行为准则。如果您不熟悉我们的行为准则政策，请在开始您的第一次贡献之前花点时间阅读该政策。

提示

有一个新的 Docker 化构建环境，请参阅 Docker 化开发。

修改主题

此主题的样式使用 SASS 和一个名为 Wyrm 的自定义 CSS 框架。我们使用 Webpack 和 node-sass 来构建 CSS。 Webpack 用于监视更改、重建静态资源以及重建 Sphinx 演示文档。

注意

Node 的安装不在本文档的范围内。您需要 Node 10+ 版本才能对此主题进行更改。

设置你的环境

  1. 安装 Sphinx 和文档构建依赖项。

    $ pip install -e '.[dev]'

  2. 在本地安装 Webpack、node-sass 和主题依赖项。

    $ npm install

进行更改

可以使用 Webpack 编译和测试对主题的更改。

$ npm run dev

此脚本将执行以下操作

  1. 安装和更新任何依赖项。

  2. 从 SASS 源文件构建静态 CSS。

  3. 构建演示文档。

  4. 监视 SASS 文件和文档的更改，并在检测到任何更改时重建所有内容。

或者，如果您不需要监视文件，可以使用发布构建脚本测试构建的资源

$ npm run build

Docker 化开发

如果您在您的平台上可以使用 Docker，您可以更快地开始构建 CSS 和 JS 工件，并且不必担心任何设置会溢出到您的通用环境中。

使用 Docker 构建时，我们创建一个包含构建依赖项的镜像。其中一些已经过时，因此理想情况下需要隔离容器。该镜像被标记为 sphinx_rtd_theme:latest。

在正在运行的 Docker 镜像内部，我们挂载存储库的工作副本，构建工件，最后观察工件已构建并保留在您当前的 Git 检出中。

使用以下步骤

# Builds an updated version of the docker image
$ docker-compose build

# Runs the development webserver
$ docker-compose run sphinx_rtd_theme dev

# If you want to copy stuff out of the Docker environment, run this make
# target or read the actual Makefile to see what is going on.
# We suggest running this command every time that you want to quickly build
# new CSS/JS assets
$ make docker-build-all

每次更改 Node 或 Python 需求时，都需要使用 docker-compose run sphinx_rtd_theme build 重新构建镜像。如果更改了 SASS 或 JS，则需要重新构建资源。

测试

由于向后兼容性，测试主题更改和拉取请求的质量保证非常复杂。

以下情况需要针对 CSS 或 JavaScript 的更改进行测试

  • 应测试多个现代浏览器。

  • 应测试多个视口大小的更改。我们支持大型、平板电脑和移动视口大小

  • 我们目前仅支持 HTML5 编写器。

  • 应测试 Sphinx 的多个主要版本。我们目前支持 Sphinx >=6.0

使用 tox 测试依赖项版本的组合最简单

% tox -e py312-sphinx74

如果测试和构建成功，则可以在 Sphinx 指示的目录中查看构建的文档

build succeeded, 10 warnings.

The HTML pages are in .tox/py312-sphinx74/tmp/html.
___________________________ summary ___________________________
  py312-sphinx74: commands succeeded
  congratulations :)

然后，您可以使用一系列浏览器打开此路径进行测试。

发现 UI 问题的最佳方法是比较两个或多个构建。您可以构建多个 tox 环境，并打开两者进行比较

% tox -e py312-sphinx62
...
% tox -e py312-sphinx74
...
% firefox .tox/py312-sphinx62/tmp/html/index.html
% firefox .tox/py312-sphinx74/tmp/html/index.html

您还可以使用单独的 tox 环境构建输出以进行比较。所有 tox 环境都有一个附加后缀 -qa，以允许构建同一个环境两次，而不会覆盖任何文件。在此测试场景中，您将在构建要测试的拉取请求分支的同一 tox 环境之前，从分支或标签构建。

例如，要针对标签 0.5.2 进行测试

% git checkout 0.5.2
% tox -e py310-sphinx53-qa
...
% git checkout feature/example-pull-request
% tox -e py310-sphinx53
...
% firefox .tox/py310-sphinx53-qa/tmp/html/index.html
% firefox .tox/py310-sphinx53/tmp/html/index.html

目前，最需要进行质量保证的环境是

  • py312-sphinx62

  • py312-sphinx74

  • py312-sphinx80

  • py312-sphinxlatest

  • py312-sphinxdev

翻译

翻译使用 Transifex 进行管理。您可以加入任何现有的语言团队或请求将新的语言添加到项目中。有关我们的翻译标准的更多信息，请参阅我们关于 国际化 的文档

核心团队应定期更新我们正常发布之外的翻译文件。核心团队中具有 Transifex 写入权限的人员应运行以下命令

$ python setup.py update_translations

这将提取新的消息，将消息上传到 Transifex，并将更新我们本地的翻译文件。可以将更改检入分支并进行审查。

版本控制

在发布之间，指定的软件包版本将始终是 alpha 版本，与 1.1.1alpha1 匹配。

随着拉取请求的合并和发布影响的更改，此版本将在发布之前递增。例如，如果我们合并了一个新的功能拉取请求，我们将运行 bump2version minor 将 1.1.1alpha1 递增到 1.2.0alpha1。

为了发布测试版本，我们将上传一个候选版本。我们将运行 bump2version release 将 1.2.0alpha1 递增到 1.2.0rc1。

经过测试期后，候选版本可以成为正式版本。我们将再次运行 bump2version release 将 1.2.0rc1 递增到 1.2.0。

在下面的发布过程之后，我们将再次递增版本，以便开发版本（存储库中找到的版本）始终大于最近的发布版本。我们通过运行 bump2version patch 继续进行另一个拉取请求，这会将 1.2.0 递增到 1.2.1alpha1。

发布主题

要发布新版本的主题，核心团队将执行以下步骤

  1. 使用 pip install '.[dev]' 安装所需的依赖项。

  2. 通过运行 bump2version [major|minor|patch|dev] 提升版本。这将自动增加版本号的正确部分，您不需要指定确切的版本号。我们遵循 语义版本控制 和 PEP440（关于 alpha 版本和开发版本）。版本递增应反映这些版本以及任何潜在的重大更改。

  3. 新版本默认情况下是 alpha 版本。如果这是候选版本，请运行 bump2version --allow-dirty release 将发布更新为 rc 版本。如果这是最终版本，请再次运行该命令。

  4. 更新变更日志（docs/changelog.rst）中的版本信息。

  5. 运行 python setup.py update_translations 编译新的翻译文件并更新 Transifex。

  6. 运行 npm install && npm run build 重新构建所有主题资源，请注意 package-lock.json 将使用新的软件包版本进行更新。但请注意，它也不会以对发布有风险的方式提升依赖项的版本。如果 package-lock.json 发生更改，则需要将其提交到 Git 并将其与发布一起标记。

  7. 将这些更改提交到拉取请求。

  8. 审查后合并拉取请求。

  9. 在本地检出 master 分支以进行标记。**请记住从远程拉取**。

  10. 在 Git 中标记发布：git tag $NEW_VERSION。

  11. 将标签推送到 GitHub：git push --tags origin。

  12. 将软件包上传到 PyPI

    $ rm -rf dist/
$ python setup.py sdist bdist_wheel
$ twine upload --sign --identity security@readthedocs.org dist/*

  13. 最后，通过运行 bump2version patch 打开一个新的拉取请求，将开发版本更新到下一个修补程序。使用此更改打开一个拉取请求。有关更多详细信息，请参阅上面的 版本控制。