Go to Qiita Advent Calendar 2024 Top
LoginSignup
5
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

オフグリッドAdvent Calendar 2024

Day 3
@kansouin株式会社オフグリッド

Pythonでのドキュメント生成(Shpinx)を自動化(GithubActions)

Posted at
  • GitHubActions
    pushなどする際にテスト等を自動化できるGitHubの機能
  • Shpinx
    コードからドキュメントを生成してくれるPythonライブラリ
  • GithubPages
    リポジトリからHTML、CSS、JavaScriptファイルを直接取得し、簡単にウェブサイトを公開できるサービス
これらを使ってドキュメント生成を自動化する方法を調べたのでまとめてみました

はじめに

  • ワークフロー用のYAMLファイルを、リポジトリの.github/workflows/ディレクトリに配置します(GitHubActions)
  • Sphinxの初期設定はディレクトリ名「document」で済ませている状態です(Sphinx)
コマンドライン
pip install sphinx
sphinx-quickstart document
  • requirements.txtはインストールされているパッケージの一覧です
    下記のコマンドで自動生成できます
コマンドライン
pip freeze > requirements.txt

root/
├ .github/
│　└ workflows/
│　　　└ actions.yaml
├ document/
│　├ build/
│　└ source/
├ requirements.txt
└ app/

ディレクトリ構成はこんな形です

下記の手順で進めていきます

1.ShpinxのActionを設定
↓
2.GitHubActionsでデプロイ(GithubPages用にドキュメントを配置すること)設定
↓
3.GitHubPagesの設定

ShpinxのActionの設定

ShpinxのActionを設定するところまでのコードです

.github/workflows/actions.yaml
name: Actions

on:
  push:
    branches:
      - "**"
jobs:
  build-doc:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install --no-cache-dir -r requirements.txt
      - name: Build HTML
        run: |
          sphinx-apidoc -f -o ./document/source .
          sphinx-build -b html ./document/source ./document/build

name(一番上)：ワークフロー名

ワークフローの名称です。指定しない場合はワークフローファイル名になります

on：トリガーの設定

どのタイミングでActinosが実行されるか
(上では全てのブランチがpushされた時に実行される)

  • プルリクエスト時
  • 特定のブランチを指定
  • 特定のブランチを無視
    ということも設定できます
# main,develop,「feature/で始まる全てのブランチ」が
# プルリクエストされた時に実行される
# ただし、feature/で始まって-testで終わる」ブランチは除外
pull_request:
    branches: 
          - main
          - develop
          - "feature/**"
          - !"feature/**-test"

jobs：jobのグループ

今回はShpinxのドキュメント生成だけですが、flake8のCheckやpytestなどの他にもjobがある場合には、同じインデントで追加できます

jobs:
  build-doc:
    # jobの記述
  flake8Check:
    # jobの記述
　pytest:
    # jobの記述

build-doc：job名

GitHubのActions画面で表示される名称です

runs-on：実行する仮想環境

jobを実行する仮想環境を指定します
今回はubuntuの最新版(latest)に指定します

steps：実行されるタスクのグループ

job内で実行されるタスクを定義します
上から順番に実行されていきます

name(steps内)：タスクの名称

Actions画面からjob内を詳しく表示した際の名称です

uses：呼び出すアクションの名称

GitHubActionsに用意されている処理を呼び出すことができます

  • actions/checkout：チェックアウトしてコードにアクセス
  • actions/setup-python：Pythonの環境をセットアップ

with：パラメータの設定

タスクに対して「パラメータ名：値」という形で値を渡せます
今回は、「actions/setup-python」の「python-version」に"3.11"を渡してSetUpするpythonのバージョンを3.11に指定しています。

run：実行するコマンド

「"|"(パイプ)」を入れることで複数行のコマンドを実行できます

今回のjobsの中身の処理

Checkout code：ブランチにチェックアウトする
Set up Python：pythonの実行環境を設定する
Install dependencies：pythonライブラリの依存関係をインストールする
Build HTML：ドキュメントを生成する

sphinx-apidoc -f -o ./document/source .

sphinxで.rstファイル(ドキュメントの設計図)を生成
(今回はroot(".")以下のモジュールから./document/sourceにrstファイルを生成)

sphinx-apidocのオプション

  • f：既存の.rstファイルを上書き
  • F：フルサイズのSphinxプロジェクトを生成
  • o：出力ファイルを置くディレクトリ。存在しない場合は作成される
  • e：モジュールごとに個別のrstファイルを生成

Sphinx-apidoc公式ページ

sphinx-build -b html ./document/source ./document/build

.rstファイルから、ドキュメントを生成
(今回は./document/sourceからrstファイルを読み込み、./document/buildにドキュメントを生成)

sphinx-sphinx-buildの主なオプション

  • b：ビルダーを選択します。デフォルトはHTMLです
  • a： すべての出力ファイルを強制的に書き出します(再生成)

sphinx-build公式ページ

デプロイ

(2024/12/09時点)
デプロイ(GithubPages用にドキュメントを配置する)方法が二種類あるようです

1.アーティファクトとしてデプロイする場合

(アーティファクト：生成された成果物の総称らしいです。今回ではSphinxドキュメント)
Githubの側の設定を変更します
アーティファクトとしてデプロイ.png
Sourceの箇所を「GitHub Actions」に変更

# name: Actions
# on: 
# と同じインデントで
permissions:
  id-token: write  # OIDCトークンの書き込み権限を付与
  pages: write  # GitHub Pagesへの書き込み権限を付与
　contents: write  # リポジトリの内容に対する書き込み権限を付与
# - name: Install dependencies
# - name: Build HTML
# と同じインデントで
- name: Upload artifact
　uses: actions/upload-pages-artifact@v2
　with:
  　path: ./document/build
   
- name: Deploy to GitHub Pages
　id: deployment
　uses: actions/deploy-pages@v2

  • actions/upload-pages-artifact：指定したパスのディレクトリ内の静的ファイルをGitHub Pages用のアーティファクトとしてアップロード

  • actions/deploy-pages：GitHub Pagesにアップロードしたアーティファクトをデプロイ

2.デプロイ用のブランチを切ってそこにドキュメントをデプロイする場合

Githubの側の設定を変更します
{7126EDB5-2782-48D6-AD4C-DDA003BC8FBB}.png
SettingのActions→Generalの画面下のWorkflow Permissions
{0DE203B8-F650-400D-B325-25E71A9251CF}.png
Read and Write permissionsを選択

# - name: Install dependencies
# - name: Build HTML
# と同じインデントで
- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./document/build
  # publish_branch: <新しいブランチ名>
  • peaceiris/actions-gh-pages：指定したブランチにデプロイ用のファイルを自動的にプッシュしてくれるサードパーティー製のアクションです

peaceiris/actions-gh-pagesのパラメータ

  • github_token：GITHUB_TOKENを指定します。secrets.GITHUB_TOKENで自動的に設定されるGITHUB_TOKENを使用します
  • publish_dir：デプロイしたいディレクトリを指定します
  • publish_branch: デプロイ用のブランチ名を指定します　(デフォルトではgh-pages)

peaceiris/actions-gh-pagesのソースコード

GitHubPagesの設定

Githubのリポジトリ→setting→Code and automation→Pages
Build and deploymentのSourceをデプロイ方法に合わせて変更

1.アーティファクトとしてデプロイした場合

アーティファクトとしてデプロイ.png
Sourceの箇所を「GitHub Actions」に変更されているか確認

2.デプロイ用のブランチを切ってそこにドキュメントをデプロイした場合

Deploy from a branch.png
Sourceの箇所を「Deploy from a branch」に変更
↓
「publish_branch:で設定したブランチ名」または「gh-pages」と設定するフォルダを選択して「Save」

設定したGitHubActionsを実行

画面上部のVisit siteで画面を開く
https://<username>.github.io/<repository>/の形式で公開されます

デフォルトのデザインだと画面はこんな感じです
ドキュメント画面.png

参考にさせていただいたサイト

5
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
5
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?