附录：在线部署 Sphinx 项目

当您准备向全世界展示您的文档项目时，可以选择的选项有很多。由于由 Sphinx 生成的 HTML 是静态的，因此您可以将构建 HTML 文档的过程与在您选择的平台中托管此类文件解耦。您不需要运行 Python 的复杂服务器：几乎每个网络托管服务都已足够。

因此，挑战不再是如何或在哪里提供静态 HTML，而是如何选择一个工作流，以便在源文件中每次发生更改时都自动更新已部署的文档。

以下各节描述了可用于部署在线文档的一些可用选项并提供了一些背景信息。如果您想直接进入实践部分，您可以跳至 发布您的文档来源。

Sphinx 友好部署选项

您有多种可能的方法来托管您的 Sphinx 文档。其中一些是

Read the Docs

Read the Docs 是一项在线服务，专门用于托管使用 Sphinx 以及 MkDocs 编写的技术文档。他们有许多额外功能，例如版本化文档、流量和搜索分析、自定义域、用户定义的重定向等等。

GitHub Pages

GitHub Pages 是高度集成在 GitHub 中的简单静态 Web 托管：一个项目的分支提供静态 HTML，常用作储存来源的分支，以便在来源更改时更新输出（例如使用 GitHub Actions）。它是免费使用且支持自定义域的。

GitLab Pages

GitLab Pages 和 GitHub Pages 类似，与 GitLab 集成且通常使用 GitLab CI 自动化。

Netlify

Netlify 是 JavaScript 等客户端 Web 技术增强版静态网站的复杂托管（所谓的 “Jamstack”）。它们支持无界面内容管理系统和无服务器计算。

您自己的服务器

您始终可以使用自己的 Web 服务器托管 Sphinx HTML 文档。这是一个灵活度更高的选项，但也更复杂。

这些选项全部都是不花钱的，可以花钱购买附加功能。

接纳“文档即代码”的哲学

上面列出的选项中，大多数的免费服务要求文档来源公开。而且，这些服务希望您使用 版本控制系统，这是一种将文件集合的演变成序列快照（“提交”）的形式追踪的技术。使用与用于软件开发的工具相同的工具，在纯文本文件中编写文档的做法通常称为 “文档即代码”。

如今最流行的版本控制系统是 Git，这是一种 GitHub 和 GitLab 等服务的支柱的免费开源工具。由于 Read the Docs 和 Netlify 都集成了 GitHub 和 GitLab，并且 GitHub 和 GitLab 均有一个集成 Pages 产品，自动在线构建文档的最有效方法是将来源上传到这两者之一的 Git 托管服务。

发布您的文档来源

GitHub

将现有项目上传至 GitHub 的最快方法是

  1. 注册 GitHub 账户.

  2. 创建新资料库.

  3. 打开您新资料库的 “上传文件”页面。

  4. 在操作系统文件浏览器中选择文件（在本例中为 README.rst、lumache.py、docs 目录下的 Makefile，以及 docs/source 下的所有内容），并将其拖动到 GitHub 界面以完成全部上传。

  5. 点击 提交更改 按钮。

提示

确保未上传 docs/build 目录，因为它包含 Sphinx 生成的输出，且在每次更改源时都会更改， مما قد يعقد سير عملك.

这些步骤无需访问命令行或安装任何其他软件。要了解更多信息，请阅读 this quickstart tutorial 或查阅 official GitHub documentation

GitLab

与 GitHub 类似，将项目上传到 GitLab 的最快方式是使用 Web 界面

  1. 注册 GitLab 帐户.

  2. 创建新的空项目.

  3. 逐个上传项目文件（在本例中为 README.rst、lumache.py、docs 目录下的 Makefile，以及 docs/source 下的所有内容），使用 上传文件 按钮 [1]。

此外，这些步骤无需在计算机上使用其他软件。要了解更多信息，您可以

提示

确保未上传 docs/build 目录，因为它包含 Sphinx 生成的输出，且在每次更改源时都会更改， مما قد يعقد سير عملك.

发布 HTML 文档

阅读文档

Read the Docs 与 GitHub 和 GitLab 都有集成。最快的上手方法是遵循RTD 教程，它大致基于本教程。你可以按照上一部分中的解释向 GitHub 发布你的源代码，然后直接跳至创建一个 Read the Docs 帐户。如果你选择使用 GitLab，该步骤类似。

GitHub Pages

GitHub Pages 要求你将源代码发布到GitHub 上。发布源文件后，你需要一个自动化流程，在源文件每次更改时执行 make html 步骤。使用 GitHub Actions 即可实现这一点。

在 GitHub 上发布你的源代码后，在你的代码库中创建一个名为 .github/workflows/sphinx.yml 的文件，其内容如下：

.github/workflows/
name: "Sphinx: Render docs"

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v4
    - name: Build HTML
      uses: ammaraskar/sphinx-action@master
    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: html-docs
        path: docs/build/html/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/build/html

这包含一个具有四个步骤的单一作业的 GitHub Actions 工作流程

  1. 签出代码。

  2. 使用 Sphinx 构建 HTML 文档。

  3. 将 HTML 输出的工件附加到 GitHub Actions 作业，以便于检查。

  4. 如果更改发生在默认分支上，请获取 docs/build/html 的内容并将其推送到 gh-pages 分支。

接下来，你需要指定 make html 步骤的依赖项以确保成功。为此，创建一个文件 docs/requirements.txt 并添加以下内容：

docs/requirements.txt
furo==2021.11.16

最后，你已准备好在你的代码库上启用 GitHub Pages。为此，请转到左边的侧边栏的设置，然后页面，在“源”向下菜单中选择 gh-pages 分支，然后点击保存。几分钟后，你应该可以在指定的 URL 上看到你的 HTML。

GitLab Pages

GitLab Pages 另一方面，要求你在 GitLab 上发布你的源代码。准备就绪后，你可以使用 GitLab CI 自动执行运行 make html 的过程。

在 GitLab 上发布源代码后，在你的存储库中创建名为 .gitlab-ci.yml 的文件，内容如下

.gitlab-ci.yml
stages:
  - deploy

pages:
  stage: deploy
  image: python:3.12-slim
  before_script:
    - apt-get update && apt-get install make --no-install-recommends -y
    - python -m pip install sphinx furo
  script:
    - cd docs && make html
  after_script:
    - mv docs/build/html/ ./public/
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

它包含一个包含多个步骤的 GitLab CI 工作流

  1. 安装必要的依赖项。

  2. 使用 Sphinx 构建 HTML 文档。

  3. 将输出移到已知工件位置。

提示

你将需要通过输入支付方式来验证你的帐户 （你将被收取少量费用，之后将报销）。

之后，如果管道成功，你应该能够在指定的 URL 中看到你的 HTML。