📝

自分の開発したツールに初めてちゃんとしたドキュメントを作成した話

2023/09/09に公開

React

こんにちは。calloc1347です。

突然ですが、皆さんはoss特有のドキュメントについて憧れたことはありませんか？

(graphql-yogaのドキュメント)

こういう感じのドキュメントがあると、綺麗でいいなと思いますよね。

そこで今回は、このようなドキュメントを自分の開発したツールに作成してみました。

利用技術

今回は、以下の技術を利用してドキュメントを作成しました。

Docuaurusは、React製の静的サイトジェネレーターです。
様々なossで利用されており、マークダウン式でドキュメントを記述することができます。

このDocusaurusのビルドにおいて、Github Actionsを利用します。

今回紹介するツール

今回ドキュメントを作成したツールは、以下の二つです。

raxtestは、openapiスキーマからテスト定義ファイルを生成し、テストを実行するツールです。
また、openapi2raxtestは、openapiスキーマからraxtestのテスト定義ファイルを生成するツールです。

raxtestの利点として、

非同期での並行テストが可能
ログイン処理への対応
openapiスキーマからテスト定義ファイルの生成対応
CI/CDに組み込みやすいjson形式での出力

等が存在します。

Raxtestに関する詳しい記事は、以下の記事を参照してください。

ドキュメントの作成

Docusaurusのインストール

まずは、Docusaurusをインストールします。
以下のコマンドを実行します。

pnpm dlx @docusaurus/init@latest init docs classic

このようにすることで、docsというディレクトリにDocusaurusのプロジェクトが作成されます。

Github Actionsの構成ファイルの作成

次に、Github Actionsの構成ファイルを作成します。
今回は、.github/workflowsディレクトリにgh-pages.ymlという名前で以下の内容のファイルを作成しました。

# Sample workflow for building and deploying a Docusaurus site to GitHub Pages
name: Deploy Docusaurus with GitHub Pages dependencies preinstalled

on:
  # masterブランチへのpushに対応する
  push:
    branches: ["master"]
  # プルリクエストでのCIに対応する
  pull_request:
    types: [opened, synchronize]

  # 手動での実行に対応する
  workflow_dispatch:

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15


    # 実行ステップ
    steps:
      - uses: actions/checkout@v2

      - uses: pnpm/action-setup@v2.2.4
        with:
          version: 8.6.3

      - name: Setup Node.js environment
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: "pnpm"
          cache-dependency-path: "docs/pnpm-lock.yaml"

      # 依存関係のインストール
      - name: install dependencies
        run: pnpm install --frozen-lockfile
        working-directory: docs

      - name: Build
        run: |
          pnpm run build
        working-directory: docs

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: docs/build

  # Deployment job
  deploy:
    # masterブランチのときのみ実行する
    if : github.ref == 'refs/heads/master'
    # 必要な権限を付与する
    permissions:
      pages: write # to deploy to Pages
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

このビルドの設定ファイルでは、以下のことを行っています。

まず、buildジョブでは、pnpmに対応するセットアップを行った後に依存関係をインストールし、ビルドを行います。
ビルドを行った後、それをアーティファクトとしてアップロードします。

ここで利用しているアクションは、actions/upload-pages-artifact@v2とactions/deploy-pages@v2のペアです。

actions/upload-pages-artifact@v2は、ビルドしたファイルをアーティファクトとしてアップロードするアクションです。
actions/deploy-pages@v2は、アーティファクトをGithub Pagesにデプロイするアクションです。
この二つのアクションを利用することで、Github PagesにDocusaurusのビルド結果をデプロイすることができます。