为 Jupyter Book 贡献

为 Jupyter Book 贡献#

欢迎来到 jupyter-book 仓库！我们很高兴您在这里，并希望为项目贡献力量。✨

请务必查看我们的行为准则

可执行书籍社区遵循此行为准则，以确保我们的在线空间对所有贡献者来说都是愉快、包容且富有成效的。

开发指南#

有关开发约定、实践和基础设施的信息，请参见executablebooks/开发指南。

文档指南#

Jupyter Book 的文档灵感来自Diataxis 文档框架。 这主要将文档分为四个主要领域：

  • 教程是面向学习的分步指南。 它们让学习者了解工具的工作原理，并激发他们进一步学习的兴趣。 教程位于文档的专门部分。

  • 操作指南是较短的指南，告诉读者如何完成某项任务。 它们假设读者对 Jupyter Book 有一定的背景知识（通常是已经阅读过教程）。 它们侧重于“做事”，而不是冗长的解释。 操作指南构成了 Jupyter Book 文档的大部分内容，并按各种主题分成了多个部分。

  • 参考文档全面描述了 Jupyter Book 的结构和功能。 它更程序化，叙事性较少，更关注涵盖 Jupyter Book 中的所有配置和选项，而不是描述何时以及如何使用它们。 Jupyter Book 在主题部分之后有一个参考部分。 此外，它还有一个组织级别的参考部分。

  • 解释是关于 Jupyter Book 相关主题和概念的高层次讨论。 它们不太关注做事，而更多关注于如何理解 Jupyter Book 的工作原理。 Jupyter Book 目前没有专门的解释部分，但欢迎添加解释性内容，并可能创建一个专门的部分。

这四个领域并不是 Jupyter Book 文档的严格规则，但在决定文档内容和位置时，应作为参考。 任何符合此框架的文档贡献（例如，添加新教程，添加操作指南部分）都非常受欢迎！

入门指南#

要开始使用 Jupyter Book 的代码库，请按照以下步骤操作：

克隆并安装包#

git clone https://github.com/executablebooks/jupyter-book
cd jupyter-book

接下来，进行安装：

python -m pip install -e .[testing,code_style]

这将本地安装 Jupyter Book，以及用于测试的包和确保代码风格的包。

安装预提交钩子#

Jupyter Book 使用 pre-commit 在提交代码之前确保代码风格和质量。 这确保了 Jupyter Book 的外观和感觉在时间和开发者之间保持一致。 当您使用 pip install -e .[code_style] 安装 Jupyter Book 时，pre-commit 也会被安装。

要在您的克隆中启用 pre-commit，请从仓库根目录运行以下命令：

pre-commit install

从现在开始，当您向 Jupyter Book 提交代码时，pre-commit 将确保您的代码符合一些检查的要求。

运行测试#

对于代码测试，Jupyter Book 使用 pytest。 您可以使用以下命令运行所有测试，或仅运行不需要额外安装的测试：

>> pytest -m 'not requires_chrome and not requires_tex'

您也可以使用 tox 在多个隔离环境中运行测试，并且也不需要初始依赖项的安装（参见 tox.ini 文件以获取可用的测试环境和进一步的解释）：

>> tox -e py39-sphinx4 -- -m 'not requires_chrome and not requires_tex'

两者都会运行 Jupyter Book 测试套件，除了 PDF 测试。 这是因为运行 PDF 生成测试需要完整的 LaTeX 环境，而您可能没有设置。

Note

Jupyter Book 使用 pytest-xdist 来并行运行测试。 您可以通过使用 -n 参数后跟您希望使用的 CPU 数量来利用这一点。 例如：pytest -n 4。这将使测试运行得更快。

测试 PDF 生成#

如果您想测试（或尝试）PDF 的生成，请按照以下步骤操作：

通过 HTML 生成 PDF，请确保您安装 Jupyter Book 时包含 pdfhtml 选项： pip install -e .[pdfhtml]。这将安装 pyppeteer， which runs a headless chrome session to convert your book to PDF. Next, follow the installation instructions at 从书籍HTML构建PDF. You should then be able to build your book’s PDF through HTML.

To generate PDFs via LaTeX, make sure you install a working LaTeX distribution locally. Do so by following the instructions in 使用LaTeX构建PDF.

If you have installed the requirements for both HTML and LaTeX generation, you should be able to run the full test suite with pytest.

GitHub Actions Artifacts#

A test included for each pull request is to build the docs as PDF files using both the pdfhtml and pdflatex writers. These tests build the pdf file and then save them as artifacts attached to each workflow run.

These pdf files can be retrieved from the top right corner of a workflow run.

Jupyter Book的存储库结构#

本节涵盖了 Jupyter Book 存储库 的一般结构，并解释了各个部分的位置。

Jupyter Book 存储库包含两个主要部分：

MyST Markdown#

Jupyter Book 支持一种名为“MyST Markdown”的 Jupyter Markdown 扩展版本。关于 MyST 语法及其使用方法的信息，请参见 MyST-Parser 文档。

命令行工具和 Python 包#

这是用于帮助创建和构建书籍的工具。可以在 ./jupyter_book 找到。

  • commands/ 文件夹包含 CLI。这是用户通过命令行创建、构建和管理书籍的接口。

  • sphinx.py 模块构建书籍。

  • yaml.py 模块处理配置。

  • toc.py 模块准备目录。

其他模块处理 Jupyter Book 中更具体的功能——更多信息请参见其模块文档字符串。

模板 Jupyter Book#

Jupyter Book 附带了一个小型模板书籍，用于展示内容。可以使用 jupyter-book build 立即构建。可以在 jupyter_book/book_template 找到。

示例#

以下是一些示例，说明如何使用此代码来帮助您入门。

  • 当有人运行 jupyter-book create mybook/ 时，create.py 模块使用 jupyter_book/book_template/ 中的模板生成一个空模板。

  • 当有人运行 jupyter-book build mybook/ 时，build.py 模块遍历您的页面内容文件，并使用 page/ 模块将每个文件转换为 HTML 并放置在 mybook/_build 中。

希望这个解释能帮助您了解各个部分如何组合在一起。如果有任何问题，请随时 打开一个问题寻求帮助！

Jupyter Book 技术栈中的其他主要工具#

Jupyter Book 依赖于 Python / Sphinx 生态系统中的一系列开源工具。这些工具承担了 Jupyter Book 的大部分繁重工作，也是许多改进和变更需要进行的地方。以下是主要工具及其支持的功能类型的列表：