付録: Sphinxプロジェクトをオンラインにデプロイする¶

ドキュメントプロジェクトを公開する準備が整ったら、多くの選択肢があります。Sphinxによって生成されたHTMLは静的であるため、HTMLドキュメントのビルドプロセスと、選択したプラットフォームでのファイルのホスティングプロセスを分離できます。Pythonを実行する高度なサーバーは必要ありません。事実上、すべてのウェブホスティングサービスで十分です。

したがって、課題は静的HTMLをどのように、どこに提供するかではなく、ソースファイルに変更があるたびにデプロイされたドキュメントを自動的に更新するワークフローをどのように選択するかです。

以下のセクションでは、オンラインドキュメントをデプロイするためのいくつかのオプションと、背景情報を説明します。実践的な部分に直接進みたい場合は、ドキュメントソースを公開するに進んでください。

Sphinxフレンドリーなデプロイオプション¶

Sphinxドキュメントをホストするための選択肢はいくつかあります。そのいくつかは次のとおりです。

Read the Docs: Read the Docs は、SphinxとMkDocsで記述された技術ドキュメントのホスティングに特化したオンラインサービスです。バージョン管理されたドキュメント、トラフィックと検索の分析、カスタムドメイン、ユーザー定義のリダイレクトなど、多くの追加機能を備えています。
GitHub Pages: GitHub Pages は、GitHubと緊密に統合されたシンプルな静的ウェブホスティングです。静的HTMLはプロジェクトのブランチの1つから提供され、通常ソースは別のブランチに保存されるため、ソースが変更されるたびに（たとえば、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にアップロードする最も簡単な方法は、次のとおりです。

GitHubアカウントにサインアップする.
新しいリポジトリを作成する.
新しいリポジトリの「ファイルをアップロード」ページを開きます。
オペレーティングシステムのファイルブラウザでファイル（README.rst、lumache.py、docsディレクトリの下にあるmakefile、およびdocs/sourceの下にあるすべて）を選択し、GitHubインターフェースにドラッグしてすべてアップロードします。
変更をコミットボタンをクリックします。

注意

docs/buildディレクトリは、Sphinxによって生成された出力が含まれており、ソースを変更するたびに変わるため、ワークフローが複雑になるため、アップロードしないでください。

これらの手順では、コマンドラインにアクセスしたり、追加のソフトウェアをインストールしたりする必要はありません。詳細については、このクイックスタートチュートリアルを読んだり、GitHub公式ドキュメントを参照してください。

GitLab¶

GitHubと同様に、プロジェクトをGitLabにアップロードする最も速い方法は、ウェブインターフェースを使用することです。

GitLabアカウントにサインアップする.
新しい空のプロジェクトを作成する.
ファイルのアップロードボタン[1]を使用して、プロジェクトファイル（README.rst、lumache.py、docsディレクトリの下にあるmakefile、およびdocs/sourceの下にあるすべて）を1つずつアップロードします。

繰り返しますが、これらの手順では、コンピューターに追加のソフトウェアは必要ありません。詳細については、次のことができます。

このチュートリアルに従って、マシンにGitをインストールします。
GitLabユーザーのドキュメントを参照して、プラットフォームの可能性を理解します。

注意

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
    - 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

これは、4つのステップからなる単一ジョブを持つGitHub Actionsワークフローです。

コードをチェックアウトします。
Sphinxを使用してHTMLドキュメントをビルドします。
HTML出力をGitHub Actionsジョブの成果物に添付して、簡単に検査できるようにします。
変更がデフォルトブランチで発生した場合、docs/build/htmlの内容を取得し、gh-pagesブランチにプッシュします。

次に、make htmlステップが成功するために必要な依存関係を指定する必要があります。そのためには、docs/requirements.txtファイルを作成し、次の内容を追加します。

docs/requirements.txt¶

furo==2021.11.16

最後に、リポジトリでGitHub Pagesを有効にする準備が整いました。そのためには、設定に移動し、左側のサイドバーにある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

これは、複数のステップからなる1つのジョブを持つGitLab CIワークフローです。

必要な依存関係をインストールします。
Sphinxを使用してHTMLドキュメントをビルドします。
出力を既知の成果物の場所に移動します。

注意

支払い方法を入力してアカウントの有効化を行う必要があります（少額が請求されますが、後に返金されます）。

その後、パイプラインが成功すると、指定されたURLでHTMLを確認できるはずです。