附錄：線上部署 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 的最快方法是

  1. 註冊一個 GitHub 帳戶.

  2. 建立一個新的儲存庫.

  3. 開啟您新儲存庫的「上傳檔案」頁面。

  4. 在您的作業系統檔案瀏覽器中選擇檔案（在您的情況下為 README.rst、lumache.py、docs 目錄下的 makefile，以及 docs/source 下的所有內容），並將它們拖曳到 GitHub 介面以全部上傳。

  5. 點擊提交變更按鈕。

注意

請確保您沒有上傳 docs/build 目錄，因為它包含 Sphinx 產生的輸出，並且每次您變更來源時都會變更，從而使您的工作流程複雜化。

這些步驟不需要存取命令列或安裝任何其他軟體。若要了解更多資訊，請閱讀這個快速入門教學或查閱官方 GitHub 文件

GitLab

與 GitHub 類似，將您的專案上傳到 GitLab 的最快方法是使用網頁介面

  1. 註冊一個 GitLab 帳戶.

  2. 建立一個新的空白專案.

  3. 使用上傳檔案按鈕 [1] 逐個上傳專案檔案（在您的情況下為 README.rst、lumache.py、docs 目錄下的 makefile，以及 docs/source 下的所有內容）。

同樣，這些步驟不需要您電腦上的其他軟體。若要了解更多資訊，您可以

注意

請確保您沒有上傳 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/
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 工作流程，其中包含一個包含四個步驟的任務

  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。為此，請前往左側邊欄的Settings，然後Pages，在「Source」下拉式選單中選取 gh-pages 分支，然後點擊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.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。