附录：在线部署 Sphinx 项目¶

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

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

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

Sphinx 友好的部署选项¶

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

Read the Docs: Read the Docs是一个在线服务，专门托管用 Sphinx 和 MkDocs 编写的技术文档。它们有许多额外功能，例如版本化文档、流量和搜索分析、自定义域、用户定义的重定向等。
GitHub Pages: GitHub Pages是一个简单的静态网页托管服务，与GitHub紧密集成：静态 HTML 从项目的一个分支提供，通常源文件存储在另一个分支中，以便在源文件更改时更新输出（例如使用GitHub Actions）。它是免费使用的，并支持自定义域。
GitLab Pages: GitLab Pages是一个与 GitHub Pages 类似的概念，与GitLab集成，通常使用GitLab CI进行自动化。
Netlify: Netlify是一个复杂的静态站点托管服务，通过客户端网络技术（如 JavaScript）增强（即所谓的“Jamstack”）。它们提供对无头内容管理系统和无服务器计算的支持。
您自己的服务器: 您始终可以使用自己的网络服务器来托管 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 的最快方法是使用网页界面

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

同样，这些步骤不需要在您的计算机上安装额外的软件。要了解更多信息，您可以

按照此教程在您的机器上安装 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/sphinx.yml¶

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 作业的artifacts中，以便于检查。
如果更改发生在默认分支上，则获取docs/build/html的内容并将其推送到gh-pages分支。

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

docs/requirements.txt¶

furo==2021.11.16

最后，您已准备好从分支发布 GitHub Pages。为此，请转到设置，然后单击左侧边栏中的页面，在“Source”下拉菜单中选择Deploy from a branch项，在“Branch”下拉菜单中选择gh-page分支，然后点击保存。几分钟后，您应该能够在指定的 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 文档。
将输出移动到已知 artifact 位置。

注意

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

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