この記事では、あらゆるプロジェクトに適応できる動的なドキュメント サイトを作成する方法を段階的に説明します。ドキュメントをデータベースに接続してデータを抽出して表示し、情報を確実に保存できます。常に最新です。また、AWS を使用して、コンテンツの生成からクラウドへの展開に至るプロセス全體を自動化する方法も検討します。

このソリューションには、チャートとダイアグラムのサポート、GitHub Actions のシンプルなワークフローを使用した継続的インテグレーション (CI/CD)、Terraform を使用した自動デプロイメントが含まれます。始めましょう!

---

コードとしてのドキュメントとは何ですか?

ドキュメントとその更新は、ソフトウェアを開発する多くの企業(yè)にとって重要なプロセスであり、多くの場合、有料ソリューションであるさまざまなツールを使用して実行されます。

したがって、最近では、「doc as code」 という概念が登場しました。これは、ソフトウェア開発で使用されるのと同じツールとワークフローを使用して、ドキュメントの管理、バージョン付け、展開を行うことを意味します。

このアプローチにより、ドキュメントの追跡が容易になるだけでなく、ドキュメントのメンテナンスが容易になり、コードだけでなくドキュメントでもソフトウェア開発で使用されるのと同じベスト プラクティスとの整合性が確保されます。

---

コードとして文書化するためのツール

これらのサイトの開発には、このアプローチの実裝を可能にするいくつかのプラクティスとツールを理解することが不可欠です。以下は、このチュートリアルで取り上げる最も重要な側(cè)面の詳細(xì)なリストです。

• ? Markdown: そのシンプルさとバージョン管理プラットフォームおよび靜的サイト ジェネレーターとの統(tǒng)合により、ドキュメントを作成するための最も一般的なマークアップ言語です。
• ?? Git: Git では、コードと同じようにドキュメントのバージョン管理が可能です。 Git のおかげで、ドキュメントのすべての変更が記録されるため、チームは編集を追跡し、変更を元に戻し、より効率的に共同作業(yè)を行うことができます。
• ? Gitflow: この方法論は、ドキュメントのバージョンとリビジョンを管理するための構(gòu)造化されたワークフローを提供し、本番環(huán)境に到達(dá)する前に変更が確実に承認(rèn)およびテストされるようにします。また、Gitflow はチーム間のコラボレーションを促進(jìn)し、安全で組織的な変更管理を可能にします。
• ?? クラウド サービス: AWS S3、Netlify、GitHub Pages などのサービスを使用すると、ドキュメントを低コストで展開できます。これらのサービスを使用すると、高速かつ安全で簡単にアクセスできる靜的サイトを作成できます。
• ? 靜的サイト ジェネレーター: Docusaurus、Jekyll、Hugo などのツールは、Markdown ドキュメントをナビゲート可能な Web サイトに変換し、サーバーなしでリッチで整理されたドキュメントを作成できるようにします。
• ? 継続的インテグレーション (CI/CD): CI/CD パイプライン (GitHub Actions、GitLab CI、または Jenkins など) を使用すると、新しいバージョンがマージされるか変更が承認(rèn)されるときに、ドキュメントを自動的にデプロイできます。これにより、ドキュメントが常に最新であることが保証されます。

---

Docs-as-Code の利點

• ? 一貫性と品質(zhì): バージョン管理と変更レビューを使用することで、ドキュメントの一貫性と高品質(zhì)が維持されます。
• ?? 自動化: CI/CD ツールにより、ドキュメントの展開を自動化し、更新時間を短縮し、エラーを最小限に抑えることができます。
• ?効率的なコラボレーション: Git などのツールを使用すると、チームは競合することなくドキュメントの作成と保守に協(xié)力できます。
• ?メンテナンスの簡素化: ドキュメントのメンテナンスが開発ワークフローに統(tǒng)合され、コードの進(jìn)化に応じて更新が容易になります。

---

? MkDocs

MkDocs は、?Python で書かれた靜的サイト ジェネレーターで、プロジェクトの文書化に特化して設(shè)計されています。その目標(biāo)は、書きやすく読みやすい Markdown ファイルを使用してドキュメントの作成を簡素化することです。

最小限の構(gòu)成で、MkDocs は Markdown ファイルをナビゲート可能で適切に構(gòu)造化されたドキュメント Web サイトに変換するため、ドキュメントを最新の狀態(tài)に保ちたい開発者やチームにとって理想的です。

---

?? MkDocs マテリアル

MkDocs マテリアル は、Google のマテリアル デザイン ガイドラインに準(zhǔn)拠した MkDocs の高度なテーマです。

?主な機(jī)能は次のとおりです。

• ? レスポンシブ デザイン: あらゆる畫面サイズに自動的に適応します。
• ? カスタマイズ: プロジェクトのビジュアルアイデンティティに合わせて、色、フォント、ファビコン、ロゴを簡単に変更できます。
• ? 検索インターフェイス: 高度な検索結(jié)果をグループ化し、検索した用語を強(qiáng)調(diào)表示して、ユーザーが必要な情報を見つけられるようにします。
• ? 遅延読み込み: 検索結(jié)果の遅延読み込みを?qū)g裝し、パフォーマンスを向上させ、読み込み時間を短縮します。
• ? 統(tǒng)合: Google Analytics、Disqus、GitHub と互換性があり、トラフィック分析、ユーザー フィードバック、プロジェクト リポジトリへの直接接続が容易になります。

---

??人魚

Mermaid は、テキストから図やチャートを作成するための JavaScript ライブラリです。 MkDocs マテリアルと統(tǒng)合することで、Mermaid を使用すると、外部ツールを使用せずに、ドキュメント內(nèi)でフローチャート、エンティティ関係図、その他のチャートなどの視覚化を生成できます。

---

?ダイナミックページ: ジンジャ

Jinja は、Python 辭書の変數(shù)とデータを HTML に埋め込み、Web ページを動的にするライブラリです。このライブラリは、動的 HTML の生成とパーソナライズされた電子メールの送信によく使用されます。

---

?ドキュサウルスの概要

Docusaurus は、2007 年に Meta によって開発されたオープンソース プロジェクトで、ドキュメント Web サイトの作成、展開、保守を迅速かつ効率的な方法で簡素化します。 Markdown と MDX を使用してコンテンツを作成できるほか、React 上に構(gòu)築されたコアにより、プロジェクトの特定のニーズに合わせてスタイルを完全にカスタマイズできます。

さらに、Docusaurus は @docusaurus/theme-mermaid プラグインを通じて Mermaid をサポートしており、ドキュメント內(nèi)にチャートや図を直接組み込むことができます。

---

?コードとしての図

Diagram as Code は、従來のグラフィック ツールを使用するのではなく、コードを通じて図を作成できるアプローチです。図を手動で構(gòu)築する代わりに、テキスト ファイルにコードを記述して、図の構(gòu)造、コンポーネント、接続を定義します。

このコードはグラフィック イメージに変換されるため、ソフトウェア プロジェクトへの統(tǒng)合と文書化が容易になります。これは、アーキテクチャ図やフロー図をプログラムで作成および更新する場合に特に役立ちます。

?コードとしての図: クラウド図の作成例

前述したように、ダイアグラム を使用すると、主要なクラウド テクノロジーのアイコンを使用してブループリントを生成できます。これらの図の表現(xiàn)はノードを通じて行われ、この例ではすべてのクラウド関連のノードと AWS サービスを使用します。

これを作成した方法の詳細(xì)については、Diagram as Code に関する私の記事を參照してください。完全な実裝はこのリポジトリにあります。

---

?ユースケース: 機(jī)械學(xué)習(xí)プロジェクトのドキュメント サイトの作成

このユースケースでは、? を含む機(jī)械學(xué)習(xí)プロジェクトのドキュメント サイトを作成します。病院のデータ。目標(biāo)は、最初に MkDocs を使用してインタラクティブなドキュメント サイトを構(gòu)築し、後でそれを Docusaurus に移行することです。このサイトには、ビジュアル ダイアグラムの埋め込みや SQLite データベースからのデータの動的更新など、特定の要件を満たす靜的コンポーネントと動的コンポーネントの両方が含まれます。

---

?ドキュメント サイトの主な機(jī)能

1. 視覚的表現(xiàn): 機(jī)械學(xué)習(xí)パイプラインのアーキテクチャを効果的に示すために、ダイアグラム (コードとしてのダイアグラム) で作成した図を埋め込みます。
2. 動的データ更新: ドキュメントには、正確さと関連性を確保するために SQLite データベース からこの情報を取得して、バージョンと最終更新日が動的に表示されます。
3. データのサンプル: ドキュメントには、例として合成データを紹介する Synthea 患者テーブルのサンプルが含まれます。

---

?サイトのページ

このため、ドキュメント サイトには次のページがあります:

• ?ホーム: ドキュメントのホームページ
• ?テーブル:Synthea データ テーブルとその用途の説明。
• ?アーキテクチャ:AWS でホストされるデータ処理アーキテクチャの詳細(xì)な概要。
• ?用語集: プロジェクト全體で使用される用語の用語集

---

MkDocs の実裝

このセクションでは、MkDocs を使用してドキュメント プロジェクトを最初からセットアップする手順を説明し、その整理されたディレクトリ構(gòu)造について説明します。

? MkDocs の前提條件

始めるには、次の ?Python ライブラリをインストールする必要があります:

MkDocs とマテリアルをインストールします

  pip install mkdocs mkdocs-material

追加のライブラリをインストールして動的コンテンツ更新を有効にします

  pip install aiosql pandas sqlite3 jinja2 shutil

---

? Mkdocs: プロジェクトのセットアップ

プロジェクトを初期化する

新しい MkDocs プロジェクトを作成することから始めます。ターミナルで次のコマンドを?qū)g行します:

   mkdocs new mkdocs
   cd mkdocs

このコマンドは、デフォルトの構(gòu)造を持つ基本的な MkDocs プロジェクトを作成します。

ディレクトリ構(gòu)造を調(diào)べる

MkDocs サイトが作成されたら、次のファイルとフォルダーはデフォルトでは含まれていないため、追加する必要があります。?
參照用にこの投稿の最後にリポジトリへのリンクが記載されていることに注意してください。各コンポーネントについては以下で詳しく説明します。

  pip install mkdocs mkdocs-material

---

?Mkdocs: コンポーネントの概要

---

? Mkdocs: mkdocs.yml の構(gòu)成

プロジェクト構(gòu)造を設(shè)定したら、mkdocs.yml ファイルから始めて、段階的に構(gòu)成していきます。このファイルは、ドキュメント サイトの構(gòu)造と設(shè)定を定義します。どのように構(gòu)成する必要があるかは次のとおりです:

mkdocs.yml

  pip install mkdocs mkdocs-material

この 設(shè)定ファイル では、主に nav セクションでメニューからアクセスできるページを確認(rèn)できます。次に、次のセクションで説明する Mermaid 拡張機(jī)能を指定します。最後に、テーマ セクションではマテリアル テーマを適用し、このライブラリ內(nèi)で使用できるスタイルとコンポーネントを有効にします。

---

?? Mkdocs: マーメイド拡張機(jī)能

前述したように、Mermaid は、テキストから図やチャートを作成するための JavaScript ライブラリです。以下にいくつかの例を示します。この例では、これを使用して、ドキュメントの テーブル ページでエンティティ関係図 (ERD) を生成します。

リポジトリでは、Synthea の公式ドキュメントにあるエンティティ関係図 (ERD) に基づいてこのコードを構(gòu)築する方法を確認(rèn)できます。次のリンクでテーブル ページの例を確認(rèn)することもできます: tables.md.

---

?? Mkdocs: Jinja を使用した動的コンテンツ

ドキュメント サイトの動的コンテンツ生成を有効にするために、Jinja を使用してテンプレートを処理し、プレースホルダーを?qū)g際のデータに置き換えます。以下は段階的な內(nèi)訳です??:

1. テンプレートフォルダーをセットアップする
   
   サイトのすべての Markdown ファイルを保存するための template という名前のフォルダーを作成します。これらのファイルにはプレースホルダーが含まれている必要があります。たとえば、index.md には、{{database.version_date}} や {{database.version}} のようなプレースホルダーがある場合があります。

2. プレースホルダーを使用する
   
   プレースホルダーは、Markdown ファイル內(nèi)の動的変數(shù)です。これらの変數(shù)は、Python 辭書を使用して関連データを挿入することで自動的に更新されます。

3. update.py を使用して動的コンテンツを生成する

   • 動的データが必要なセクションを特定して、Markdown テンプレートを準(zhǔn)備します。
   • 私のリポジトリで入手可能な Python スクリプト (update.py) を使用して、テンプレートを処理します。スクリプトは次のタスクを?qū)g行します。
     • データベース接続: SQLite データベースに接続して最新の値を取得します。
     • テンプレート レンダリング: Jinja ライブラリを使用して、プレースホルダーをデータベースのデータに置き換えます。
     • ファイル生成: 更新された Markdown ファイルを docs フォルダーに出力し、MkDocs でレンダリングできるようにします。

  pip install mkdocs mkdocs-material

  pip install aiosql pandas sqlite3 jinja2 shutil

これらの手順に従うことで、ドキュメント サイトの更新プロセスを自動化し、手動で編集しなくてもコンテンツが動的かつ関連性を維持できるようにすることができます。

---

データテーブルの動的更新

次の例では、tables.md ファイルの內(nèi)容を更新して、データベースの persons テーブルの例を示します。これを行うには、Markdown ファイル內(nèi)にプレースホルダー {{table.person}} を作成します。そのアイデアは、persons テーブルからデータを動的にフェッチし、Jinja ライブラリと pandas を使用してクエリ結(jié)果を Markdown テーブル形式に変換することです。

プレースホルダーを使用した tables.md ファイルの例を次に示します。

   mkdocs new mkdocs
   cd mkdocs

プロセスは次のとおりです:

1. データベースのクエリ: スクリプトは SQLite データベースの persons テーブルをクエリして、関連するレコードを取得します。
2. Markdown に変換: pandas を使用すると、クエリの結(jié)果が Markdown テーブル形式に変換されます。
3. プレースホルダーを置き換える: tables.md ファイル內(nèi)の {{table.person}} プレースホルダーは、生成された Markdown テーブルに置き換えられます。

   ? docs/
     ├── ? img/
     ├── `architecture.md`
     ├── `glossary.md`
     ├── `index.md`
     ├── `tables.md`
     ├── ? template/
     │   ├── ? db/
     │   │   ├── ? data/
     │   │   │   ├── hospital.db
     │   │   ├── ? queries/
     │   ├── `architecture.md`
     │   ├── `glossary.md`
     │   ├── `index.md`
     │   ├── `tables.md`
     │   └── `update.py`
   ? infraestructure/
   ? github/
     ├── ? workflows/
     │   ├── main.yml
   ? mkdocs.yml

このようにして、ドキュメントには常に最新のデータが反映され、データベースの実際のコンテンツに基づいた動的な例が表示されます。

---

?? Mkdocs: 最終的なワークフロー

1. テンプレートの作成: docs/template ディレクトリでページを作成します。
2. update.py を?qū)g行: 動的コンテンツを入力し、docs/output に最終ファイルを生成します。
3. ローカルでプレビュー: mkdocsserve を使用して、ローカルホスト上のサイトをプレビューします。
4. デプロイメント用のビルド: mkdocs build を使用して、docs/ フォルダーに靜的サイトを生成します。
5. デプロイ: Terraform を使用してサイトを AWS S3 バケットにデプロイします。詳細(xì)な手順については、この投稿の展開セクションを參照してください。

---

?ドキュサウルスの実裝

次のセクションでは、Docusaurus を使用してドキュメント サイトを?qū)g裝する方法について、詳細(xì)な手順と洞察を提供します。これには、セットアップ、カスタマイズ、展開オプションが含まれます。

---

? Docusaurus の主な特徴

• ? Mermaid のサポート: MkDocs と同様に、Docusaurus は図を埋め込むために Mermaid をサポートしています。
• ?? React コンポーネント: React 上に構(gòu)築された Docusaurus を使用すると、動的コンポーネントをドキュメントに統(tǒng)合できます。
• ? 動的コンテンツ: Python スクリプトを利用して、SQLite データベースからコンテンツを動的に取得および更新します。

---

? Docusaurus のセットアップ: ゼロから

Docusaurus を使い始めるには、簡単なセットアップ プロセスに従います。これは MkDocs で使用した手順とよく似ていますが、ツールが異なります。

1. 新しい Docusaurus プロジェクトを作成します: まず、Node.js をインストールし、次のコマンドを?qū)g行して新しい Docusaurus サイトを作成します。

  pip install mkdocs mkdocs-material

1. Mermaid パッケージをインストールします: 人魚図を有効にするには、必要なパッケージをインストールします。

  pip install aiosql pandas sqlite3 jinja2 shutil

1. 開発サーバーを?qū)g行します: インストールしたら、プロジェクト ディレクトリに移動し、開発サーバーを?qū)g行します。

   mkdocs new mkdocs
   cd mkdocs

1. サイトにアクセス: あなたのサイトはローカルで http://localhost:3000 に公開されます。

---

? Docusaurus のカスタマイズ: 構(gòu)成

構(gòu)成ファイル docusaurus.config.js で、タイトル、テーマ、ナビゲーションをカスタマイズし、図のレンダリング用に Mermaid などの機(jī)能を有効にします。
Mermaid を有効にするためのスニペットの例:

  pip install mkdocs mkdocs-material

---

? Docusaurus ホームページのカスタマイズ

ホームページをカスタマイズするには、src/components/Homepage features/index.js ファイルを変更します。ここで、FeatureList オブジェクトを調(diào)整して、ホームページに表示される機(jī)能を更新できます。

---

? Docusaurus のコンテンツの構(gòu)成と構(gòu)造

MkDocs と同様に、Docusaurus はコンテンツの Markdown ファイル をサポートしており、次のように構(gòu)造を編成します。

1. テンプレート フォルダー: Markdown ファイルを docs/template ディレクトリに保存し、動的データを取得してこれらのテンプレートに入力する Python スクリプト (update.py に似ています) を作成します。
2. カテゴリ ファイル (__category__.json): サイドバー內(nèi)のドキュメントの順序を管理するには、各フォルダーに __category__.json ファイルを作成します。例えば：

  pip install aiosql pandas sqlite3 jinja2 shutil

__category__.json の例:

   mkdocs new mkdocs
   cd mkdocs

---

?? Jinja による動的データ

データベース テーブルなどの動的コンテンツを組み込むには、リポジトリにある update.py という名前の ?Python スクリプトを使用します。

このスクリプトは、SQLite データベースからデータを取得し、テンプレート フォルダーに保存されている Markdown ファイルを処理します。次に、取得したデータでこれらのファイルを更新し、docs フォルダーにコピーして、サイトのレンダリングの準(zhǔn)備をします。

このワークフローは、MkDocs で実裝したものと同様のアプローチに従って、コンテンツを最新の狀態(tài)に保ち、展開の準(zhǔn)備ができていることを保証します。

---

?? Docusaurus: 最終的なワークフロー

1. テンプレートの作成: docs/template ディレクトリ內(nèi)で Markdown ファイルを開発します。
2. Python スクリプトの実行: スクリプトを使用して、テンプレートにデータを動的に入力します。
3. ローカルでプレビュー: npx docusaurus start を?qū)g行してサイトをプレビューします。
4. 展開用のビルド: 準(zhǔn)備ができたら、npx docusaurus build を使用して靜的サイトを生成します。
5. デプロイ: AWS S3 などの優(yōu)先プラットフォームで靜的ファイルをホストします。

---

?導(dǎo)入

このセクションでは、AWS S3 をホスティングに使用した MkDocs と Docusaurus の両方の デプロイメントプロセス について説明します。どちらのツールでも展開手順は同じですが、MkDocs は Python ベースであり、Docusaurus は JavaScript ベースであるため、インストール プロセスが異なります。

---

Terraform を使用したインフラストラクチャのセットアップ

靜的ドキュメント サイトを AWS S3 にデプロイするには、Terraform を使用して必要なリソースをプロビジョニングおよび構(gòu)成します。このセットアップでは、S3 バケットを定義し、靜的 Web サイト ホスティングを有効にし、バケット ポリシーを使用して読み取り専用アクセスを許可するパブリック アクセスを構(gòu)成します。 main.tf ファイルはリポジトリにあります。

---

? S3 導(dǎo)入の主要コンポーネント

1. S3 バケットの作成: ドキュメントがホストされる S3 バケットを作成するリソース。
2. 靜的 Web サイト ホスティング: 靜的 Web ホスティングの構(gòu)成。index.html と error.html をメイン ドキュメントとエラー ドキュメントとして設(shè)定します。
3. パブリック アクセス設(shè)定: S3 バケットへのパブリック アクセスを管理し、読み取り専用アクセス用に設(shè)定されていることを確認(rèn)します。
4. バケット ポリシー: S3 バケットからドキュメント コンテンツを取得するためのパブリック アクセスを許可します。

完全な Terraform ファイル と、リポジトリにサイトをデプロイするための対応する構(gòu)成にアクセスできます。

Terraform 構(gòu)成ファイル:

• mkdocs ファイル
• ドキュサウルス ファイル

自動デプロイのための GitHub アクション ワークフロー: デプロイ プロセスを自動化する CI/CD パイプラインもリポジトリに含まれています。

• mkdocs ファイル
• ドキュサウルス ファイル

GitHub アクションの構(gòu)成
設(shè)定 > の GitHub リポジトリ シークレット で AWS 認(rèn)証情報を必ず設(shè)定してください。 秘密 > アクション。これにより、GitHub Actions が AWS アカウントに安全にアクセスし、変更をメイン ブランチにプッシュするときに S3 へのファイルのアップロードなどのアクションを?qū)g行できるようになります。

---

リポジトリ

以下は、ドキュメント サイトを展開するためのすべてのコードへのリンクです。役に立ったと思ったら、スター??を付けてフォローしていただくと、新しい記事の通知が屆きます。これは、テクノロジー コミュニティで成長し、より多くのコンテンツを作成するのに役立ちます。

• MkDocs デプロイメント: MkDocs の GitHub リポジトリ

• Docusaurus デプロイメント: Docusaurus の GitHub リポジトリ

---

?最終結(jié)論: MkDocs 対 Docusaurus

どちらのソリューションも実裝は簡単ですが、次の項目でいくつかの違いを検討します。最適なソリューションはどれであるかは、実裝する必要があるコンテキスト、知識、複雑さによって異なります。

• ? 言語とカスタマイズ: MkDocs は Python ベースで、シンプルな YAML 構(gòu)成とテンプレートを備えており、素早いセットアップに最適です。一方、Docusaurus は React ベースで、高度なカスタマイズとインタラクティブなコンポーネントを提供し、ビジュアルをより詳細(xì)に制御する必要があるユーザーに適しています。
• ? マークダウンとレンダリング: どちらも Markdown を使用しますが、Docusaurus ではインタラクティブな要素が使用できるため、動的コンテンツに適しています。
• ?? 複雑さ: Docusaurus は、ログイン システムを使用するアプリケーションなど、複雑なドキュメント アプリケーションに適しています。 MkDocs はよりシンプルですが、Docusaurus はスタイルと機(jī)能の柔軟性が高くなります。
• ? コミュニティ: Docusaurus には Discord と 74 個のプラグインによる強(qiáng)力なコミュニティがありますが、MkDocs はコミュニティ サポートとして GitHub ディスカッションに依存しています。
• ?? Amazon 導(dǎo)入: 靜的サイトを S3 にデプロイしてデプロイメント コストを削減したり、自動デプロイメントに CI/CD を使用したりすることもできます。

---

?參考文獻(xiàn)

1. Mkdocs: https://www.mkdocs.org/
2. Mkdocs-マテリアル: https://squidfunk.github.io/mkdocs-material/
3. 図: https://diagrams.mingrammer.com/
4. ドキュサウルス: https://docusaurus.io/
5. ジンジャ: https://jinja.palletsprojects.com/en/stable/
6. Git Book - doc as code とは: https://www.gitbook.com/blog/what-is-docs-as-code
7. ドキュメントを作成します: https://www.writethedocs.org/guide/docs-as-code/

以上がAWS での Docs-as-Code のデプロイ: MkDocs と Docusaurus での動的なドキュメント サイトの構(gòu)築の詳細(xì)內(nèi)容です。詳細(xì)については、PHP 中國語 Web サイトの他の関連記事を參照してください。