pdoc + GitHub Actionsを使用して，ドキュメントを自動でGitHub Pagesに公開する

概要

Pythonのdocstringからドキュメントを生成するライブラリに，sphinxなどがありますが，
今回は手軽にドキュメント生成ができるpdocというライブラリを使用してみました．
pdocとGitHub Actionsを使用して，ドキュメントを自動更新し，GitHub Pagesに公開する方法まで検討してみたので， その詳細をこちらにメモしておきます．
今回作成したコードは，こちらに共有しておりますので，よければご参照ください．

pdocとは

pdocとは，Pythonのdocstringからドキュメントを生成するツールです．
同じドキュメント生成ツールであるSphinxとは違い，
特段面倒な設定等をせずとも，ドキュメントを作成できるのがpdocの強みです．
pdocを使用することで，自身で作成したパッケージや，社内のプロジェクトのドキュメントを簡単に作成することができます．

pdocの使い方

pdocの使い方について説明したいと思います．
といっても，非常に簡単で，パッケージをインストールし，コマンドを打つだけで終わりです．

pdocをインストール

pdocではなく，pdoc3をインストールする点に注意してください．

pip install pdoc3

サンプルコードを用意する

main.pyという名前で，以下のような適当なコードを作成します．
この際ドキュメントを生成するために，適当なdocstringを追加しておきます．

class SampleClass(object):
    """This is a smaple class."""

    def __init__(self, a: int, b: float, c: str) -> None:
        """Sample constructor.
        Args:
            a: integer
            b: flaot
            c: string
        """
        self.a = a
        self.b = b
        self.c = c

    def sample(self, x: int) -> int:
        """Sample method.
        Args:
            x: integer
        Return:
            integer
        """
        return self.a + x

    def call(self, input_str: str) -> str:
        """Sample call method.
        Args:
            x: str
        Return:
            str
        """
        return self.c + input_str

pdocでドキュメントを作成する

コードの準備ができましたら，いよいよドキュメントを作成します．
コマンドラインから以下を実行するだけです．

pdoc --html --force -o docs <MODULE_NAME>

各オプションの意味は以下の通りです． * --html ... HTML形式でのドキュメント生成 * -o docs ... ./docsディレクトリにドキュメントを生成 * --force ... すでにドキュメントが存在する場合に上書き

今回はmain.pyのドキュメントを生成したいので，以下を実行します．

pdoc --html --force -o docs main.py

GitHub Pagesに公開する

上記で作成したドキュメントをGitHub Pagesに公開します．
まず上記のコード，及びドキュメントをGitHubのレポジトリにpushします．

次にレポジトリページのSettings -> PagesからGitHub Pagesの設定ページに移動します．

PagesのページのSource項目にて，対象のブランチをmain，対象のフォルダを/docsとします．

設定を保存してしばらくすると，指定されたURLにドキュメントが公開されているはずです！

参考ページ

GitHub Actionsを使用して，ドキュメントを自動更新する

最後にドキュメントの更新をGitHub Actionsで自動化したいと思います．
今回はイベントトリガーとして，.pyファイルの変更を含むmainブランチに対するpush / pull request，及び手動実行の3つを設定します．
ワークフローでは，以下の手順で実行していきます．

1. python，及びpoetryのセットアップ
2. poetryによる依存パッケージのダウンロード
3. pdocを用いたドキュメント生成
4. 新しいドキュメントをpush

./github/workflowsというディレクトリを作成し，pdoc.ymlというファイルに以下を記述します．

name: generate_pdoc
# イベントトリガーの設定
on:
  push:
    branches:
      - main
    paths:
      - "*.py"
  pull_request:
    branches:
      - main
    paths:
      - "*.py"
  workflow_dispatch:

jobs:
  generate_pdoc:
    name: generating pdoc
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      
      # set up python
      - name: Setting up python.
        uses: actions/setup-python@v1
        with:
          python-version: 3.8
        
      # install poetry
      - name: Install Poetry
        run: |
          curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
      
      - name: Add path for Poetry
        run: echo "$HOME/.poetry/bin" >> $GITHUB_PATH
      
      # install dependencies
      - name: Install Dependencies
        run: poetry install --no-interaction --no-dev

      # pdocでドキュメントを生成
      - name: Pdoc
        run: poetry run pdoc --html -o docs --force main.py
      
      # 差分をgitにpushする
      # ref: https://zenn.dev/lollipop_onl/articles/eoz-gha-push-diffs
      - name: Push new docs
        run: |
          git remote set-url origin https://github-actions:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}
          git config --global user.name "${GITHUB_ACTOR}"
          git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
          if (git diff --shortstat | grep '[0-9]'); then \
            git add .; \
            git commit -m "Generating docs via GitHub Actions"; \
            git push origin HEAD:${GITHUB_REF}; \
          fi

GitHub Actions内で発生した差分をpushする手順に関しては，こちらの記事を参考にしました．
こちらのyamlファイルをpushすれば，設定完了です．

試しに先程のmain.pyに，以下の変更を加え，mainブランチにpushしてみます．

"""This documentation was updated by github actions.
Please see my blog for the detail: https://yiskw713.hatenablog.com/pdoc-github-actions
"""


class SampleClass(object):
    """This is a smaple class."""

    # (以下略)

すると，GitHubのレポジトリページのActionsタブにて，pdocによるドキュメント作成のワークフローと，GitHub Pagesのデプロイのワークフローが実行されているのが確認できます．

GitHub Pagesで作成されたwebサイトのURLにアクセスしてみると，変更されているのが確認できました！

参考: https://yiskw713.github.io/pdoc_sample/main.html

まとめ

pdocとGitHub Actionsを使用して，pythonプロジェクトのドキュメントを自動で生成し，GitHub Pagesにて公開してみました．
特段煩雑な設定も必要なく，簡単にドキュメントページを作成でき，非常に便利だと感じました．

参考リンク

• pdoc – Auto-generate API documentation for Python projects
• yiskw713/pdoc_sample
• pdoc を試してみた：Python パッケージ／モジュールの docstring から API ドキュメントを自動生成する - はむ吉（のんびり）の練習ノート
• Contexts - GitHub Docs
• Events that trigger workflows - GitHub Docs
• GitHub Actions でワークフロー中に発生した差分を Push する

リンク