贡献

感谢您帮助我们改进这份文档和我们的库！

如果您觉得这份文档不清楚或缺少步骤，请打开一个问题。

开发工作流程

如果您有兴趣贡献代码或文档，我们强烈建议您在开发环境中安装 sphinx-gallery 的开发版本。如果您不熟悉 git/github 工作流程，请参阅 Github 的贡献项目指南。

本指南假设您熟悉 Github 工作流程，并侧重于特定于贡献 Sphinx-Gallery 的方面。

获取最新源代码

您可以从我们的Github 仓库获取最新的开发源代码。

git clone https://github.com/<your github user name>/sphinx-gallery

创建一个专用环境

我们强烈建议您创建一个虚拟环境来开发 Sphinx Gallery，以将其与系统上的其他 Python 安装隔离开来。

创建一个新的虚拟环境

python -m venv <file folder location>

使用以下方法之一激活虚拟环境

source <file folder location>/bin/activate  # Linux/macOS
<file folder location>\Scripts\activate.bat  # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1

安装依赖项

Sphinx Gallery 的大多数依赖项都在 pyproject.toml 中列出，可以从这些文件安装。

python -m pip install --editable ".[dev]"

Sphinx Gallery 要求安装setuptools。它通常与 python 一起打包，但如果需要，可以使用 pip 安装。

python -m pip install setuptools

安装以供开发

可编辑安装意味着环境 Python 将始终使用您代码的最新更改版本。要以可编辑模式安装 Sphinx Gallery，请确保您在 sphinx-gallery 目录中。

cd sphinx-gallery

然后使用可编辑标志安装

python -m pip install -e .

验证安装

通过运行测试来检查您是否已准备好

python -m pytest sphinx_gallery

以及构建文档

cd doc
make html

安装 pre-commit 钩子

pre-commit 钩子会检查贡献代码和文档中的拼写和格式等内容。要设置 pre-commit 钩子

python -m pip install pre-commit
pre-commit install

指南

测试

所有代码贡献都应进行测试。我们使用pytest 测试框架和 tinybuild 来构建测试页面。测试可以在 sphinx_gallery/tests 中找到。

tinybuild

tinybuild 被设计为最小的完整 sphinx 文档构建，您可以使用 make html 从 tinybuild/doc 运行它，以获得传统的构建体验。

tinybuild 在 tests/test_full.py 中运行，使用 tests/doc/tinybuild 中的 .rst 文档文件构建一个测试页面。测试会检查 html 输出，以验证 .rst 文件中指令的行为。