附录：将Sphinx项目部署上线¶

当您准备好向世界展示您的文档项目时，有许多可用的选项可以做到这一点。由于 Sphinx 生成的 HTML 是静态的，您可以将构建 HTML 文档的过程与在您选择的平台上托管此类文件分开。您不需要运行 Python 的复杂服务器：几乎每个 Web 托管服务都足够了。

因此，挑战不在于如何或在哪里提供静态 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 是一个复杂的静态网站托管服务，通过客户端 Web 技术（所谓的 "Jamstack"）进行增强。他们提供对无头内容管理系统和无服务器计算的支持。
您自己的服务器: 您始终可以使用自己的 Web 服务器来托管 Sphinx HTML 文档。这是提供更多灵活性的选项，但也更复杂。

所有这些选项都是免费的，并且可以选择支付额外的功能费用。

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

上述大多数选项的免费服务要求您的文档源文件公开可用。此外，这些服务期望您使用 Version Control System，这是一种将一组文件的演变跟踪为一系列快照（“提交”）的技术。使用与软件开发相同的工具在纯文本文件中编写文档的做法通常被称为 "Docs as Code"。

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

公开您的文档源文件¶

GitHub¶

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

注册一个GitHub账户。
创建一个新的存储库。
打开你的新存储库的 the "Upload files" page 。
选择操作系统文件浏览器中的文件（在您的情况下为 README.rst、lumache.py、docs 目录下的 makefiles 以及 docs/source 下的所有内容），并将它们拖到 GitHub 界面中以上传它们。
点击 Commit changes 按钮。

备注

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

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

GitLab¶

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

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

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

按照 this tutorial 在您的计算机上安装 Git。
浏览 GitLab User documentation 以了解该平台的可能性。

备注

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

发布您的 HTML 文档¶

Read the Docs¶

Read the Docs 提供与 GitHub 和 GitLab 的集成。开始的最快方法是按照 the RTD tutorial，它大致基于本教程。您可以按照上一节中的说明在 GitHub 上发布您的源文件，然后直接跳到 Creating a Read the Docs account。如果您选择 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 作业的工件，以便于检查。
如果更改发生在默认分支上，请将 docs/build/html 的内容推送到 gh-pages 分支。

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

docs/requirements.txt¶

furo==2021.11.16

最后，您可以 publish GitHub Pages from a branch 了。为此，请转到 Settings，然后在左侧边栏中选择 Pages，在“Source”下拉菜单中选择“Deploy from a branch”项，在“Branch”下拉菜单中选择 gh-page 分支，然后单击 Save。几分钟后，您应该能够在指定的 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.14-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 文档。
将输出移动到已知的工件位置。

备注

需要通过输入付款方式来 validate your account （将收取一小笔费用，然后将予以退还）。

然后，如果工作流成功，您应该能够在指定的 URL 看到您的 HTML。