附录：在线部署 Sphinx 项目¶

当您准备好向世界展示您的文档项目时，有很多选项可供选择。由于 Sphinx 生成的 HTML 是静态的，您可以将构建 HTML 文档的过程与在您选择的平台上托管这些文件解耦。您不需要运行 Python 的复杂服务器：几乎每个 Web 托管服务都可以满足需求。

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

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

Sphinx 友好的部署选项¶

您有几个可能的选项来托管您的 Sphinx 文档。其中一些是

Read the Docs: Read the Docs 是一项在线服务，专门用于托管用 Sphinx 以及 MkDocs 编写的技术文档。它们具有许多额外的功能，例如版本控制文档、流量和搜索分析、自定义域名、用户定义的重定向等等。
GitHub Pages: GitHub Pages 是一种简单的静态 Web 托管，与 GitHub 紧密集成：静态 HTML 从项目的某个分支提供，通常源文件存储在另一个分支中，以便每次源文件更改时都可以更新输出（例如，使用 GitHub Actions）。它是免费使用的，并支持自定义域名。
GitLab Pages: GitLab Pages 是与 GitHub Pages 类似的概念，与 GitLab 集成，通常通过 GitLab CI 自动化。
Netlify: Netlify 是一种用于静态站点的复杂托管，通过客户端 Web 技术（如 JavaScript，所谓的 “Jamstack”）增强。它们为无头内容管理系统和无服务器计算提供支持。
您自己的服务器: 您始终可以使用自己的 Web 服务器来托管 Sphinx HTML 文档。这是提供更多灵活性的选项，但也更复杂。

所有这些选项都是零成本的，可以选择付费以获得额外的功能。

拥抱 “文档即代码” 理念¶

上面列出的大多数选项的免费服务都要求您的文档源文件公开可用。此外，这些服务希望您使用版本控制系统，这是一种跟踪文件集合演变为一系列快照（“提交”）的技术。使用与软件开发相同的工具以纯文本文件编写文档的实践通常被称为 “文档即代码”。

当今最流行的版本控制系统是 Git，这是一个免费且开源的工具，是 GitHub 和 GitLab 等服务的支柱。由于 Read the Docs 和 Netlify 都与 GitHub 和 GitLab 集成，并且 GitHub 和 GitLab 都有集成的 Pages 产品，因此在线自动构建文档最有效的方法是将您的源文件上传到这些 Git 托管服务中的任何一个。

发布您的文档源文件¶

GitHub¶

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

注册一个 GitHub 帐户.
创建一个新的存储库.
打开您的新存储库的 “上传文件”页面。
在您的操作系统文件浏览器中选择文件（在您的情况下为 README.rst、lumache.py、docs 目录下的 makefile 文件以及 docs/source 下的所有内容），并将它们拖到 GitHub 界面以全部上传。
单击提交更改按钮。

注意

确保您不要上传 docs/build 目录，因为它包含 Sphinx 生成的输出，并且每次您更改源文件时它都会更改，从而使您的工作流程复杂化。

这些步骤不需要访问命令行或安装任何其他软件。要了解更多信息，请阅读此快速入门教程或查阅官方 GitHub 文档

GitLab¶

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

注册一个 GitLab 帐户.
创建一个新的空白项目.
使用上传文件按钮 [1] 逐个上传项目文件（在您的情况下为 README.rst、lumache.py、docs 目录下的 makefile 文件以及 docs/source 下的所有内容）。

同样，这些步骤不需要您计算机上的其他软件。要了解更多信息，您可以

按照本教程在您的机器上安装 Git。
浏览 GitLab 用户文档以了解平台的功能。

注意

确保您不要上传 docs/build 目录，因为它包含 Sphinx 生成的输出，并且每次您更改源文件时它都会更改，从而使您的工作流程复杂化。

发布您的 HTML 文档¶

Read the Docs¶

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
      with:
        persist-credentials: false
    - 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 工作流程，其中包含一个包含四个步骤的作业

检出代码。
使用 Sphinx 构建 HTML 文档。
将 HTML 输出附加到 GitHub Actions 作业的工件，以便于检查。
如果更改发生在默认分支上，则获取 docs/build/html 的内容并将其推送到 gh-pages 分支。

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

docs/requirements.txt¶

furo==2021.11.16

最后，您已准备好在您的存储库上启用 GitHub Pages。为此，转到左侧边栏的设置，然后转到 Pages，在“Source”下拉菜单中选择 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 工作流程，其中包含一个包含多个步骤的作业

安装必要的依赖项。
使用 Sphinx 构建 HTML 文档。
将输出移动到已知的工件位置。

注意

您需要通过输入付款方式验证您的帐户（您将被收取少量费用，然后退还）。

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