Ops Frontier Docusaurus

Ops Frontier の開発においてはドキュメントをマークダウンで記述し、 Docusaurus で配信する。 このリポジトリでは、 Docusaurus のテンプレートを利用して、マークダウンのプレビューを行う仕組みを提供する。

各リポジトリでは docs 配下にDocusaurus のルールに従ってドキュメントを記述する。開発者はこのテンプレートをインストールすることにより、マークダウンのプレビューを配信時と同じフォーマットで見ることができる。

以下に利用手順を示す。

1. テンプレートルールに基づいたドキュメントの記載

docs ディレクトリ配下にドキュメントの種別ごとにディレクトリを作成し、 Docusaurs の autogenerate のルールに従ってマークダウンを配置する。以下に例を示す。

docs
├── devDesign
│   └── index.md
└── devGuide
    ├── CICD
    │   ├── _category.json
    │   ├── github.md
    │   └── PR.md
    ├── index.md
    └── Rust
        ├── _category.json
        ├── crate.md
        └── dockerhub.md

ここで devGuide, devDesign はドキュメントの種別ごとのディレクトリである。このテンプレートでは以下のドキュメント種別をサポートしている。

| ディレクトリ | ラベル | 説明 | | ------------------ | --------------- | ----------------- | | devGuide | 開発者ガイド | 開発者向けのガイドである | | devDesign | 設計書 | アーキテクチャや実装方式を記載したものである | | devSpecification | 仕様書/テスト項目書 | 機能仕様およびテスト項目を記載したものである | | adminGuide | 管理者マニュアル | 管理者マニュアルである | | userGuide | 利用者マニュアル | 利用者マニュアルである |

それぞれのディレクトリの配下は docusaurus の autogeneratedに従ったファイル構成としなければならない。

2. インストール

このテンプレートをインストールしなければならない。package.json がないプロジェクトにおいては先立って package.json を作成しておく必要がある。

npm install @ops-frontier/docusaurus@latest

3. プレビュー

プレビューを実行するためには以下を実行する

npx ops-frontier-docusaurus start

このコマンドによりローカルの 3000番ポートに Webpack が起動するため、これをブラウザで開くことでプレビューできる。