附录：在线部署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页面类似的概念，与 GitLab 并且通常是自动的 GitLab CI 取而代之的是。

Netlify

Netlify 是一个复杂的静态站点主机，通过客户端Web技术(如所谓的JavaScript)增强 "Jamstack" )。它们支持无头内容管理系统和无服务器计算。

Your own server

您始终可以使用自己的Web服务器来托管Sphinx HTML文档。这种选择提供了更大的灵活性，但也带来了更大的复杂性。

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

拥抱“以文档为代码”的哲学

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

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

发布文档源

GitHub

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

1. Sign up for a GitHub account <https://github.com/signup> _.

2. Create a new repository <https://github.com/new> _.

3. 打开 the "Upload files" page 您的新储存库。

4. 在您的操作系统文件浏览器上选择文件(在您的情况下 README.rst ， lumache.py 下的Make文件 docs 目录，以及下面的所有内容 docs/source )，拖拽到GitHub界面即可全部上传。

5. 按下 Commit changes 纽扣。

备注

请确保您没有上载 docs/build 目录，因为它包含Sphinx生成的输出，并且它会在您每次更改源代码时更改，从而使您的工作流复杂化。

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

GitLab

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

1. Sign up for a GitLab account <https://gitlab.com/users/sign_up> _.

2. Create a new blank project <https://gitlab.com/projects/new> _.

3. 上传项目文件(在您的情况下 README.rst ， lumache.py 下的Make文件 docs 目录，以及下面的所有内容 docs/source )逐个使用 Upload File 按钮 [1].

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

• 关注 this tutorial 在您的计算机上安装Git。

• 浏览 GitLab User documentation 以了解该平台的可能性。

备注

请确保您没有上载 docs/build 目录，因为它包含Sphinx生成的输出，并且它会在您每次更改源代码时更改，从而使您的工作流复杂化。

[1]

在写这篇文章的时候， uploading whole directories to GitLab using only the web interface 尚未实施。

发布您的HTML文档

阅读文档

Read the Docs 提供与GitHub和GitLab的集成。最快的开始方法是遵循 the RTD tutorial ，它大致基于这个。您可以按照说明在GitHub上发布您的来源 in the previous section ，然后直接跳到 Creating a Read the Docs account .如果您选择GitLab，则过程类似。

GitHub页面

GitHub Pages 需要您 publish your sources 在……上面 GitHub 。在此之后，您将需要一个自动过程来执行 make html 每次信号源发生变化时都要执行步骤。这可以使用以下工具来实现 GitHub Actions 。

在GitHub上发布源代码后，创建一个名为 .github/workflows/sphinx.yml 在您的存储库中包含以下内容：

.githeb/工作流/

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操作工作流，其中包含四个步骤的单个作业：

1. 签出代码。

2. 使用Sphinx构建HTML文档。

3. 将构件的HTML输出附加到GitHub操作作业，以便于检查。

4. 如果更改发生在默认分支上，则获取 docs/build/html 并把它推到 gh-pages 布兰奇。

接下来，您需要指定 make html 迈向成功的一步。为此，创建一个文件 docs/requirements.txt 并增加以下内容：

docs/requirements.txt

furo==2021.11.16

最后，你已经准备好 enable GitHub Pages on your repository 。有关这方面的信息，请访问 Settings ，那么 Pages 在左侧边栏上，选择 gh-pages 分支，然后点击 Save 。几分钟后，您应该能够在指定的URL处看到您的HTML。

GitLab页面

GitLab Pages _，另一方面，需要您 publish your sources 在……上面 GitLab 。准备好后，您可以自动执行运行过程 make html 使用 GitLab CI 。

在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配置项工作流，其中包含多个步骤的一个作业：

1. 安装必要的依赖项。

2. 使用Sphinx构建HTML文档。

3. 将输出移动到已知的构件位置。

备注

你将需要 validate your account 通过输入付款方式(您将被收取少量费用，然后将得到报销)。

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

Previous

从代码自动生成文档

Next

从这里到哪里去