开发入门#

本节介绍了在本地开始开发该主题的最简单方法，以便您可以做出贡献。 它使用自动化并尽可能少的步骤来完成任务。

如果您熟悉并更喜欢更手动地设置，请参阅 设置手动开发环境 部分。

测试预发布和夜间构建#

您可以在您的项目中测试 PyData Sphinx 主题的 alpha、beta 和候选发布版本。 为此，请使用 --pre 标志通过 pip 安装

$ pip install --pre pydata-sphinx-theme

如果存在 alpha、beta 或 rc 版本，pip 将安装它。

您可以在项目的持续集成测试套件中使用 --pre 标志，以便在发布之前捕获回归或错误。

如果您更喜欢冒险，pydata-sphinx-theme 拥有夜间构建，您可以尝试按照 scientific-python/upload-nightly-action README 中提供的说明 安装夜间构建的轮子。

在项目的 CI 任务中安装夜间构建的轮子是帮助主题开发人员提前发现错误的好方法。

贡献更改的工作流程#

我们遵循 典型的 GitHub 工作流程，包括以下步骤：

  • 创建该仓库的个人分支和本地克隆

  • 为您的贡献创建一个分支

  • 打开一个拉取请求

  • 修复各种 linter 和检查的结果

  • 完成代码审核

对于每个拉取请求 (PR)，文档都会被构建并部署，以便更轻松地审查 PR 中的更改。 要访问此预览，请在 CI/CD 任务中点击 Read the Docs 预览（PR 底部的 CI/CD 任务部分，请注意您可能需要点击“显示所有检查”才能访问该任务）。

以下部分更详细地介绍了贡献步骤。

克隆仓库#

首先，您需要获取 pydata-sphinx-theme 代码库的副本。 您可以像这样克隆它进行本地开发

  1. **分叉仓库**，这样您就在 GitHub 上拥有了自己的副本。 有关更多信息，请参阅 GitHub 分叉指南。

  2. **将仓库克隆到本地**，以便您拥有一个本地副本供工作。

    $ git clone https://github.com/{{ YOUR USERNAME }}/pydata-sphinx-theme
$ cd pydata-sphinx-theme

安装工具#

构建 Sphinx 站点使用了 Python 和 Jinja 的组合来管理 HTML、scss 和 JavaScript。 为简化此过程，我们使用了一些辅助工具

  • Sphinx 主题构建器 以自动化方式编译 Web 资源。

  • pre-commit 用于在提交之前自动强制执行代码标准和质量检查。

  • tox 用于自动化常见的开发任务。

  • pandoc 通用文档转换器。

特别是，tox 可用于自动创建隔离的本地开发环境，其中安装了所有正确的软件包，以处理主题。 本指南的其余部分重点介绍了使用 tox 来开始使用基本环境。

另请参阅

本页面上的信息涵盖了入门的基础知识，有关手动编译资源的信息，请参阅 设置手动开发环境。

设置 tox#

首先，安装 tox

$ pip install tox

您可以从命令行调用 tox 来执行构建主题所需的常见操作。 tox 使用隔离的环境运行，因此每个操作都在本地目录（.tox）中安装其软件包。 对于常见的开发操作，您只需要使用 tox，无需设置任何其他软件包。

设置 pre-commit#

pre-commit 允许我们在每次进行新的 Git 提交时对代码库运行一些检查。 这样可以确保我们的代码符合标准并进行基本的质量控制。

使用以下命令安装 pre-commit

$ pip install pre-commit

然后导航到该仓库的文件夹并像这样激活它

$ pre-commit install

这将安装每次使用 Git 提交时运行 pre-commit 所需的依赖项。

注意

您的 pre-commit 依赖项将安装在您调用 pre-commit、tox 等的环境中。 它们不会安装在 tox 使用的隔离环境中。

或者，如果您不想全局安装 pre-commit 及其依赖项，可以使用 tox 来运行检查

tox -e run lint

使用 tox 的缺点是，这不会安装所需的挂钩以在每次提交之前自动运行检查，因此您需要手动运行它。

构建文档#

现在您已经安装了 tox 并克隆了仓库，您需要安装 Graphviz 才能构建文档。 要安装 Graphviz，请按照 Graphviz 文档中的说明操作，针对您的操作系统。

安装了 tox 和 Graphviz 之后，您可以构建文档。 要使用 tox 构建文档，请运行以下命令

$ tox run -e docs-dev

这将安装必要的依赖项并构建位于 docs/ 文件夹中的文档。 生成的文档将放置在 docs/_build/html 文件夹中。 如果文档已构建，它只会重新构建已更新的页面。 您可以打开其中的一个 HTML 文件以在本地预览文档。

或者，您可以使用内置的 Python http.server，通过以下命令来启动它

$ python -m http.server -d docs/_build/html/

这将打印一个本地 URL，您可以在浏览器中打开该 URL 来浏览 HTML 文件。

您还可以使用以下命令，通过实时重载来提供文档服务

$ tox run -e docs-live

此命令将构建文档并监视 doc 文件夹中的任何更改，并自动重新构建文档。

更改内容并重新构建#

现在您已经构建了文档，请编辑其中一个源文件，以查看文档如何在新的构建中更新。

  1. **编辑页面**。 例如，在任何页面上添加一个词或修复一个错别字。

  2. **使用 tox run -e docs-dev 重新构建文档**

这次应该会快得多，因为 tox 正在重新使用之前创建的环境，并且因为 Sphinx 缓存了您没有更改的页面。

编译 CSS/JS 资源#

CSS 和 JS 资源的源文件位于 src/pydata_sphinx_theme/assets 中。 然后，它们将与主题一起构建和捆绑（例如，scss 将转换为 css）。

要使用 tox 编译 CSS/JS 资源，请运行以下命令

$ tox run -e compile-assets

这将编译所有资源并将它们放置在适当的文件夹中，以便与文档构建一起使用。

注意

已编译的资源**不会提交到 Git**。当我们发布新版本时，sphinx-theme-builder 会自动捆绑这些资源，但我们不会手动将这些编译后的资源提交到 Git 历史记录中。

运行开发服务器#

您可以将上述两个操作（构建文档和编译 JS/CSS 资源）组合起来，并运行开发服务器，以便对 src/ 的更改会自动与包捆绑在一起，并且文档会立即在实时预览窗口中重新加载。

要使用 tox 运行开发服务器，请运行以下命令

# note the -m flag vs. other commands in this guide
$ tox run -m docs-live-server

当您在主题上工作时，对以下任何目录进行更改

  • src/js/index.js

  • src/scss/index.scss

  • docs/**/*.rst

  • docs/**/*.md

  • docs/**/*.py

将导致开发服务器执行以下操作

  • 捆绑/复制 CSS、JS 和供应商提供的字体

  • 重新生成 Jinja2 宏

  • 重新运行 Sphinx

运行测试#

此主题使用 pytest 和 playwright 进行测试。在 test_build.py 脚本中定义了一个轻量级夹具，它使得使用此主题运行 Sphinx 构建并检查结果变得简单明了。在 test_a11y.py 中也有一些自动化的可访问性检查。

警告

目前，自动化的可访问性测试仅检查 Kitchen Sink 页面。我们正在努力将覆盖范围扩展到主题的其余部分。

此外，我们使用 pytest-regressions 来确保主题生成的 HTML 是我们预期的。此模块提供了一个 file_regression 夹具，它将检查对象的内容与磁盘上的参考文件是否一致。如果两个结构不同，则测试将失败。如果我们预期结构不同，则删除磁盘上的文件并运行测试。将创建一个新文件，后续测试将通过。

要使用 tox 运行构建测试，请运行以下命令

# this will compile the assets and run the tests (with test coverage)
# note the use of the `-m` flag vs. other commands in this guide
$ tox run -m tests

# to run the tests only without pre-compiling the assets and without coverage (for example if you recently compiled the assets)
$ tox run -e tests-no-cov

要运行可访问性检查

# this will compile the assets, build the documentation, and run the accessibility tests
$ tox run -m a11y

# to run the tests without pre-compiling the assets and without re-building the docs (for example if you recently compiled the assets or built the docs)
$ tox run -e a11y-tests

GitHub Codespaces#

如果您有良好的互联网连接，并且想要一个临时的设置，在 Codespaces 环境中处理 PyData Sphinx 主题通常更快。设置好 Codespaces 实例后，您可以运行上面的 tox 命令来构建文档、编译资源并运行测试。有关如何开始使用 Codespaces 的文档，请参见 Codespaces 文档。