概要
uvで管理しているpythonパッケージのsphinxドキュメントを、github actions経由でgithub pagesにアップロードする手順をまとめました。
sphinxをgithub pagesにデプロイする方法自体はたくさん情報があるのですが、uvと組み合わせた事例が少なかったので、大したことはしていませんが、試行錯誤の概要をメモとして残します。
前提
前回（uvとsphinxでパッケージのdocsを自動生成）の続きです。
- uvでpythonパッケージを管理
- pyproject.tomlで以下の通りタスクスクリプトを定義し
uv run task docs-generateでrstファイルおよびhtmlファイルの生成ができることを確認済み
[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に以下のように記載する。
/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して、実行したところ、無事デプロイできました。
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の公式サイトに、sphinx-action（ammaraskar/sphinx-action@master）を使ってgithub pagesにデプロイするワークフローサンプルが載っていますが、今回は使いませんでした。
sphinx-actionはrstは存在する前提でhtmlの生成とアップロードのみする仕様っぽいのですが、今回はrstファイルの自動生成もやりたかったので、taskとして自前で管理するほうが楽だと思ったためです。
buildとdeployの分離
一つのワークフローでbuildとdeployに分かれているため、artifactの受け渡しが必要になっています。アクションをまとめてしまえば、この受け渡しは不要になりますが、buildとdeployで別れていたほうがなにかとデバッグしやすいかと思い、今回はこの形式にしました。