附录:在线部署 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这样的客户端Web技术（所谓的`”Jamstack”`_）增强.他们提供对无头内容管理系统和服务器无计算的支持.

你自己的服务器

您始终可以使用自己的 Web 服务器来托管 Sphinx HTML 文档.这是提供更多灵活性的选项,但也增加了复杂性.

所有这些选项都是零成本的,可以选择支付额外功能.

拥抱”文档即代码”的理念

上述大多数选项的免费服务要求您的文档源代码是公开可用的.此外,这些服务期望您使用一个 版本控制系统 ,这是一种跟踪一系列文件演变的技术,这些文件以一系列快照（”提交”）的形式存在.使用与软件开发相同的工具编写纯文本文件的文档的做法通常被称为 “Docs as Code”.

如今最流行的版本控制系统是 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 生成的输出,每次你更改源文件时它都会变化,这会使你的工作流程复杂化.

这些步骤不需要访问命令行或安装任何额外的软件.要了解更多信息,请阅读 这个快速入门教程 或查阅 官方GitHub文档

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 上发布您的源代码,然后直接跳到 readthedocs:tutorial/index:创建一个 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.