Read the Docs

Read the Docs 是一个在线托管文档的网络服务。 他们为开源项目提供免费的网络托管服务，通过插入页面的道德广告来维持运营。 这些广告也可以通过小额的月度付款来移除，以帮助支持该项目。

Read the Docs 构建 Sphinx 网站，并不直接支持 Jupyter Book。 然而，你可以将你的书籍转换为 Sphinx 网站，以便使用 Read the Docs 发布。 这可以通过 Read the Docs 的 pre_build 任务自动化完成。

要使用 Read the Docs 发布你的书籍，请按照以下步骤操作：

1. 开始使用 Read the Docs。 为此，请按照 Read the Docs 教程 进行操作。 配置 Read the Docs 从你的书籍仓库托管一个网站。

2. 在你的仓库根目录下创建一个 .readthedocs.yml 文件。 此文件配置 Read the Docs 的行为。

3. 在你的 .readthedocs.yml 文件中添加一个 pre_build 任务。 Read the Docs 允许你在文档构建前后运行额外的脚本。 你可以利用这一点在 Read the Docs 尝试构建之前生成 Sphinx 配置 用于你的 Jupyter Book。 例如，此配置用于构建此书：

   version: 2
   
   build:
     os: ubuntu-22.04
     tools:
       python: "3.11"
     jobs:
       pre_build:
         # Generate the Sphinx configuration for this Jupyter Book so it builds.
         - "jupyter-book config sphinx docs/"
   
   python:
     install:
       - method: pip
         path: .
         extra_requirements:
         - sphinx
   
   sphinx:
     builder: html
     fail_on_warning: true
   

   有关配置文件选项的完整参考，请参阅 Read the Docs 配置文件参考。

Read the Docs 现在应该会自动为你的书籍生成 Sphinx 配置，并构建你的书籍 HTML 以在线托管。

Tip

你也可以通过使用 Read the Docs 的这个示例项目来开始：

• 示例项目

• GitHub 上的示例项目源代码

该项目本身可以复制并定制，或者在你从头开始创建希望在 Read the Docs 上发布的 Jupyter Book 项目时，可以将其用作参考。