uvとgithub actionsによるsphinxのビルドとgithub pagesアップロード



# 概要
uvで管理しているpythonパッケージのsphinxドキュメントを、github actions経由でgithub pagesにアップロードする手順をまとめました。
sphinxをgithub pagesにデプロイする方法自体はたくさん情報があるのですが、uvと組み合わせた事例が少なかったので、大したことはしていませんが、試行錯誤の概要をメモとして残します。

# 前提
[前回（uvとsphinxでパッケージのdocsを自動生成）](https://qiita.com/shimajiroxyz/private/34a3a4d8ca64a2c1443c)の続きです。

- uvでpythonパッケージを管理
- pyproject.tomlで以下の通りタスクスクリプトを定義し`uv run task docs-generate`でrstファイルおよびhtmlファイルの生成ができることを確認済み

```toml:pyproject.toml
[tool.taskipy.tasks]
docs-generate = "sphinx-apidoc -f -o docs/source src/PACKAGENAME && sphinx-build -M clean docs/source docs/build && sphinx-build -M html docs/source docs/build"
```

- docs/source/conf.pyとdocs/source/index.rstをgitで管理。例えばgitignoreに以下のように記載する。

```:.gitignore
/docs/*
!/docs/source/
/docs/source/*
!/docs/source/index.rst
!/docs/source/conf.py
```

# 準備

githubのページでリポジトリのSetting > PagesからGitHub Actionsによるgithub pagesへのdeployを有効にしてください。
詳しいやり方は他にたくさん記事があるので省略します。

# ワークフロー

以下の`.github/workflow/docs.yaml`を作成し、デフォルトブランチにpushして、実行したところ、無事デプロイできました。


```.github/workflow/docs.yaml
name: Deploy documentation to GitHub Pages

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.py'  # .pyファイルに変更があったときのみトリガー
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install uv
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
      - name: Install dependencies
        run: |
          # 必要に応じて
          sudo apt-get update
          sudo apt-get install -y portaudio19-dev
          uv venv
          uv pip install -r requirements.txt
      - name: Build documentation
        run: |
          uv run task docs-generate
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: documentation
          path: docs/build/html

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: documentation
          path: ./documentation
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./documentation
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4 
```

## 処理の流れ

### build
- OSはubuntu-latest
- リポジトリをチェックアウト
- uvをインストールし、pyproject.tomlで管理できない依存関係を導入後、タスクを実行してhtmlを生成
- 生成したhtmlを次のdeployにわたすためにアップロード。アクションをまたぐとアクション中に生成されたファイルは何もしないと削除されてしまうため必要。

### deploy
- buildでアップロードした生成物をダウンロードし、github pagesにアップロードする

# その他

### sphinx-action
[sphinxの公式サイト](https://www.sphinx-doc.org/ja/master/tutorial/deploying.html#id5)に、sphinx-action（`ammaraskar/sphinx-action@master`）を使ってgithub pagesにデプロイするワークフローサンプルが載っていますが、今回は使いませんでした。
sphinx-actionはrstは存在する前提でhtmlの生成とアップロードのみする仕様っぽいのですが、今回はrstファイルの自動生成もやりたかったので、taskとして自前で管理するほうが楽だと思ったためです。

### buildとdeployの分離
一つのワークフローでbuildとdeployに分かれているため、artifactの受け渡しが必要になっています。アクションをまとめてしまえば、この受け渡しは不要になりますが、buildとdeployで別れていたほうがなにかとデバッグしやすいかと思い、今回はこの形式にしました。