/mkdocs-sandbox

Primary LanguageJavaScript

目次

パッケージインストール

$ pnpm install

tbls

セットアップ

  1. Homebrewでtbldツールをインストール

    $ brew install k1LoW/tap/tbls

  2. パッケージインストール

    $ pnpm install

  3. Docker起動

    $ docker-compose up -d
    • Dockerでtbls docを実施することも可能だが、現在は無効にしている。

  4. マイグレーションファイル作成(更新がある場合のみ)

    $ pnpm db-generate

  5. DBマイグレーション

    $ pnpm db-migrate

  6. Github Actionsのworkflow permissionsを更新 (Github ActionsからCommit & pushできるように) alt text

  7. Github Actionsでtblsドキュメントを自動更新し、PRのコメントに詳細を記載

    • Github Actions workflows起動条件: schemaファイルを更新し、`develop'ブランチにPull Request alt text alt text

  8. PRをdevelopにmerge

  9. developでPRを作り、mainにmerge

  10. 作業終了後) Docker終了

    $ docker-compose down

github actionsをローカルで実施 (現在は、disabledディレクトリに格納中)

  1. rootフォルダに.actrcを新規作成し、以下設定

    -P mysql:8.0=mysql:8.0
-s GITHUB_TOKEN=XXXX

  2. pnpm tbls-act実施

    • tbls-doc-local.ymlファイルで記載されたアクションが実施され、docs/dbdoc/act-localにtblsファイルが生成される。

tblsとは

  • Databaseのスキーマを基に自動でDocumentationを作成するツール
  • 主なtblsコマンド
    • tbls doc: Databaseのスキーマ情報をベースにドキュメントを作成
    • tbls diff: Databaseのスキーマ情報と現在のtbls docファイルの差分を表示
  • 必要なファイル
    • .tbls.yml: configファイル。DSN(Database Source Name)やファイルの出力先を設定。ViewpointやCommentなどを設定できる。

特徴

🙆

  • tblsでできること
    • Viewpoint: データベースのスキーマに対する特定の視点やフィルタリングを設定・管理
    • Comment: テーブルやカラムにコメントを記載
    • Label: ラベル付
    • Lint: スキーマ定義に対するLintの設定

🙅

  • ある程度のカスタマイズはできるが、schemaspyほどの機能はない?(例: Anoalisで不整合テーブル検出など?)

使用検討案

  • Github ActionsでCI/CDを実施することは可能だが、DBをCloud SQLで管理していることを考えると、Cloud Buildのプロセスにtbls docを含めた方が効率的？(Github actionsだとイベントリスナーでCloud Buildのmigration完了をListenした上で、Actions workflowを開始するする必要あり?)
    • 例1) cloudbuild.yamlでmigrationファイルに変更があったら、Cloud SQL Auth Proxy実施=>migration実行=>データベース更新=>tbls doc更新
      • ただし、Build内で直接DBを更新するのはリスクがある？
    • 例2) cloudbuild.yamlでmigrationファイルに変更があったら、Cloud SQL Auth Proxy実施=>別のDBに反映=>それを本番のDBに反映

参考文献

目次に戻る

schemaspy

事前セッティング(インストール/ ダウンロード)

使用方法

A: コマンドにconfig情報直接入力=>outputファイル作成 (◯)

java -jar ./schemaspy-6.2.4.jar \
    -t mysql \
    -dp ./mysql-connector-j-9.0.0.jar \
    -db parking_app \
    -host localhost \
    -port 3306 \
    -s parking_app \
    -u root \
    -o ./output \
    -hq /opt/homebrew/bin/dot \
    -imageformat svg \
    -imagefontadjust true
  • Graphviz rendererについて以下のようなエラーが多く発生するが、無視して良さそう。((根拠 from Github issues)[schemaspy/schemaspy#833])
.ERROR - dot ~~ Warning: cell size too small for content

B: Configファイルを作成 => コマンドでconfigファイルを参照=>outputファイル作成(×: エラー解決できず、index.htmlが生成されない)

  • schemaspy.propertiesで設定情報を記載=>$ java -jar ./schemaspy-6.2.4.jar \ -configFile schemaspy.propertiesを実行

  • 以下のようなエラーが発生する。Javaランタイムが認識するクラスファイルバージョンが古いのが原因。Versionを11に変えれば解消するようだが、まだ解決できていない。

Caused by: java.lang.UnsupportedClassVersionError: org/openjdk/nashorn/api/scripting/NashornScriptEngineFactory has been compiled by a more recent version of the Java Runtime (class file version 55.0), this version of the Java Runtime only recognizes class file versions up to 52.0

C: Dockerで実施

  • 未着手

schemaspyとは

  • Databaseのスキーマを基に自動でDocumentationを作成するツール
  • Javaベース

特徴

🙆

  • 各テーブル、及びそのER図をサイトとして一覧できる。
  • Anomaliesで不整合なテーブルを検出できる。
  • Orphan Tablesで他テーブルとのRelationがないものを検出できる。
  • Searchでテーブルレベル、テーブル内のカラムレベルの検索が可能。

🙅

  • 各テーブル・カラムに対するコメントの記載や、テーブルをカテゴライズなどのカスタマイズがしにくい？
  • index.htmlを参照するためには、github pagesなどを使用する必要がある。ただし、github pagesはpublicでないとサイトを公開できない。Private公開&内部でのみサイトを公開するためには、Github Enterpriseを使用する必要がある？

参考文献

目次に戻る

MKDocs

セットアップ

  1. 仮想環境 (venv) を設定

    $ python3 -m venv venv

$ source venv/bin/activate

$ pip install mkdocs-material

$ mkdocs new .

$ mkdocs serve //2回目以降はserveのみでOK
    • 使用終了時に、$ deactivateして仮想環境も終了する。

  2. mkdocs.yml(1で自動生成)でカスタマイズ

    • 多言語設定可能
      • $ pip install mkdocs-static-i18nインストール
      • i18nプラグイン設定必要
    • docs傘下の特定のフォルダをbuildの除外に設定
      • a) $ pip install mkdocs-exclude
      • b) mkdocs.ymlのpluginで設定
    • Version管理
      • a) $ pip install mike
      • b) mkdocs.ymlのpluginで設定
      • c) $ mike deploy --push --update-aliases [version] latestで指定のversionをデプロイ
      • d) $ mike serve=>http://localhost:8000/version/にアクセス => versionタブで各versionに移動可能
      • e) Github Actions用のymlファイル作成 + Github Pagesの設定を変更

  3. mkdocs serveでローカル環境でサイトアクセス可能

  4. mkdocs buildでサイトビルド

  5. Github actionsでGithub pagesにデプロイ (.github/workflows/mkdocs-generate.yml)

MKDocsとは

  • Pythonベースで実装されるドキュメントサイトを生成するための静的サイトジェネレーター
  • Markdown形式のファイルを読み込み、ドキュメントを生成

特徴

🙆

  • テーマや多言語設定、Nav・サイドバーなどカスタマイズが可能
  • docs直下フォルダが一つのセクションとみなされ、タブになる。1フォルダ = 1セクションでシンプル。
  • 多分、Version管理もできる。こちら
  • Markdown言語しだけでなく、HTMLファイルも認識する。(Path指定してリンクからアクセス可能/ ビルド後にスタイルが消える問題が発生中)

🙅

  • MKDocs

参考文献

目次に戻る

特徴

🙆

  • 限定公開可能?

🙅

参考文献

目次に戻る