附录：在线部署 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）来增强静态网站。他们提供对 headless 内容管理系统和 serverless 计算的支持。

你自己的服务器

你可以随时使用你自己的网络服务器来托管 Sphinx HTML 文档。这是给人更多灵活性的选择，但也更复杂。

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

拥护 “文档即代码” 理念

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

现在最流行的版本控制系统是 Git，一个免费的开源工具，是 GitHub 和 GitLab 等服务的骨干。由于 Read the Docs 和 Netlify 都与 GitHub 和 GitLab 有集成，而且 GitHub 和 GitLab 都有集成的 Pages 产品，所以自动在线建立文档的最有效方法是将你的源代码上传到这些 Git 托管服务中的任何一个。

发布你的文档源码

GitHub

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

1. 注册一个 GitHub 账户。

2. 创建应该新的仓库。

3. 打开新版本库的 the “Upload files” page。

4. 在你的操作系统文件浏览器上选择文件（在你的例子中是 README.rst，lumache.py，docs 目录下的 makefiles，以及 docs/source 下的所有文件），然后把它们拖到 GitHub 界面，把它们全部上传。

5. 点击 Commit changes 按钮。

备注

确保你不上传 docs/build 目录，因为它包含了 Sphinx 生成的输出，每次你改变源头时它都会改变，使你的工作流程复杂化。

这些步骤不需要访问命令行或安装任何其他软件。要了解更多，你可以：

• Follow this interactive GitHub course to learn more about how the GitHub interface works.

• Read this quickstart tutorial to install extra software on your machine and have more flexibility. You can either use the Git command line, or the GitHub Desktop application.

GitLab

Similarly to GitHub, the fastest way to upload your project to GitLab is using the web interface:

1. Sign up for a GitLab account.

2. Create a new blank project.

3. Upload the project files (in your case README.rst, lumache.py, the makefiles under the docs directory, and everything under docs/source) one by one using the Upload File button 1.

Again, these steps do not require additional software on your computer. To learn more, you can:

• Follow this tutorial to install Git on your machine.

• Browse the GitLab User documentation to understand the possibilities of the platform.

备注

确保你不上传 docs/build 目录，因为它包含了 Sphinx 生成的输出，每次你改变源头时它都会改变，使你的工作流程复杂化。

1

At the time of writing, uploading whole directories to GitLab using only the web interface is not yet implemented.

发布你的 HTML 文档

Read the Docs

Read the Docs 提供了与 GitHub 和 GitLab 的整合。最快的入门方法是遵循 RTD 教程，它是松散地基于这个教程的。你可以在 GitHub 上发布你的源代码，如 上一节 所解释的那样，然后直接跳到 Sign up for Read the Docs。如果你选择 GitLab，过程也类似。

GitHub Pages

GitHub Pages 要求你 发布源码 在 GitHub 上发布。之后，你将需要一个自动程序，在每次改变源的时候执行 make html 步骤。这可以用 GitHub Actions 来实现。

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

.github/workflows/

name: Sphinx build

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Build HTML
      uses: ammaraskar/sphinx-action@0.4
    - name: Upload artifacts
      uses: actions/upload-artifact@v1
      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 页面 了。为此，进入 Settings，然后在左侧的 Pages，在 Source 下拉菜单中选择 gh-pages 分支，然后点击 Save。几分钟后，你应该能在指定的 URL 上看到你的 HTML。

GitLab Pages

GitLab Pages, on the other hand, requires you to publish your sources on GitLab. When you are ready, you can automate the process of running make html using GitLab CI.

After you have published your sources on GitLab, create a file named .gitlab-ci.yml in your repository with these contents:

.gitlab-ci.yml

stages:
  - deploy

pages:
  stage: deploy
  image: python:3.9-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

This contains a GitLab CI workflow with one job of several steps:

1. Install the necessary dependencies.

2. 使用 Sphinx 建立 HTML 文档。

3. Move the output to a known artifacts location.

备注

You will need to validate your account by entering a payment method (you will be charged a small amount that will then be reimbursed).

After that, if the pipeline is successful, you should be able to see your HTML at the designated URL.