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

- 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を設定するところまでのコードです

``` yaml: .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された時に実行される)
- プルリクエスト時
- 特定のブランチを指定
- 特定のブランチを無視
ということも設定できます
``` yaml:
# main,develop,「feature/で始まる全てのブランチ」が
# プルリクエストされた時に実行される
# ただし、feature/で始まって-testで終わる」ブランチは除外
pull_request:
    branches: 
          - main
          - develop
          - "feature/**"
          - !"feature/**-test"
```
### jobs：jobのグループ
今回はShpinxのドキュメント生成だけですが、flake8のCheckやpytestなどの他にもjobがある場合には、同じインデントで追加できます
```yaml
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公式ページ](https://www.sphinx-doc.org/ja/master/man/sphinx-apidoc.html)
#### sphinx-build -b html ./document/source ./document/build
.rstファイルから、ドキュメントを生成
(今回は`./document/source`からrstファイルを読み込み、`./document/build`にドキュメントを生成)

sphinx-sphinx-buildの主なオプション 
- b：ビルダーを選択します。デフォルトはHTMLです
- a： すべての出力ファイルを強制的に書き出します(再生成)

[sphinx-build公式ページ](https://www.sphinx-doc.org/ja/master/man/sphinx-build.html)
## デプロイ
(2024/12/09時点)
デプロイ(GithubPages用にドキュメントを配置する)方法が二種類あるようです

#### 1\.アーティファクトとしてデプロイする場合
(アーティファクト：生成された成果物の総称らしいです。今回ではSphinxドキュメント)
Githubの側の設定を変更します
![アーティファクトとしてデプロイ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3483796/37475e94-ec9b-2ec0-4866-b19953af3748.png)
Sourceの箇所を「GitHub Actions」に変更
``` yaml: 
# 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](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3483796/6d9f47e3-ccca-1bd4-040e-4e6ba395e7db.png)
SettingのActions→Generalの画面下のWorkflow Permissions
![{0DE203B8-F650-400D-B325-25E71A9251CF}.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3483796/36637355-ebc5-7d51-09c8-20c25ea0c35a.png)
Read and Write permissionsを選択
``` yaml: 
# - 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のソースコード](https://github.com/peaceiris/actions-gh-pages/blob/main/action.yml)
## GitHubPagesの設定
Githubのリポジトリ→setting→Code and automation→Pages
Build and deploymentのSourceをデプロイ方法に合わせて変更

#### 1.アーティファクトとしてデプロイした場合
![アーティファクトとしてデプロイ.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3483796/37475e94-ec9b-2ec0-4866-b19953af3748.png)
Sourceの箇所を「GitHub Actions」に変更されているか確認


#### 2\.デプロイ用のブランチを切ってそこにドキュメントをデプロイした場合
![Deploy from a branch.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3483796/1f458d27-74cd-f1ca-f849-b79343d4facb.png)
Sourceの箇所を「Deploy from a branch」に変更
↓
「publish_branch:で設定したブランチ名」または「gh-pages」と設定するフォルダを選択して「Save」

#### 設定したGitHubActionsを実行

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

デフォルトのデザインだと画面はこんな感じです
![ドキュメント画面.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3483796/1703b741-4e14-261f-3de4-0ec6d32250fb.png)

## コードの完成形
#### 1.アーティファクトとしてデプロイする場合
``` yaml: .github/workflows/actions.yaml
name: Actions

on:
  push:
    branches:
      - "**"

permissions:
  id-token: write  # OIDCトークンの書き込み権限を付与
  pages: write  # GitHub Pagesへの書き込み権限を付与
　contents: write  # リポジトリの内容に対する書き込み権限を付与

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: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./document/build   
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2
```
#### 2\.デプロイ用のブランチを切ってそこにドキュメントをデプロイする場合
``` yaml: .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: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./document/build
        # publish_branch: <新しいブランチ名>
```
## 参考にさせていただいたサイト

https://docs.github.com/ja/actions

https://www.sphinx-doc.org/ja/master/index.html

https://github.com/peaceiris/actions-gh-pages