この記事では、あらゆるプロジェクトに適応できる動的なドキュメント サイトを作成する方法を段階的に説明します。ドキュメントをデータベースに接続してデータを抽出して表示し、情報を確実に保存できます。常に最新です。また、AWS を使用して、コンテンツの生成からクラウドへの展開に至るプロセス全体を自動化する方法も検討します。
このソリューションには、チャートとダイアグラムのサポート、GitHub Actions のシンプルなワークフローを使用した継続的インテグレーション (CI/CD)、Terraform を使用した自動デプロイメントが含まれます。始めましょう!
ドキュメントとその更新は、ソフトウェアを開発する多くの企業にとって重要なプロセスであり、多くの場合、有料ソリューションであるさまざまなツールを使用して実行されます。
したがって、最近では、「doc as code」 という概念が登場しました。これは、ソフトウェア開発で使用されるのと同じツールとワークフローを使用して、ドキュメントの管理、バージョン付け、展開を行うことを意味します。
このアプローチにより、ドキュメントの追跡が容易になるだけでなく、ドキュメントのメンテナンスが容易になり、コードだけでなくドキュメントでもソフトウェア開発で使用されるのと同じベスト プラクティスとの整合性が確保されます。
これらのサイトの開発には、このアプローチの実装を可能にするいくつかのプラクティスとツールを理解することが不可欠です。以下は、このチュートリアルで取り上げる最も重要な側面の詳細なリストです。
MkDocs は、?Python で書かれた静的サイト ジェネレーターで、プロジェクトの文書化に特化して設計されています。その目標は、書きやすく読みやすい Markdown ファイルを使用してドキュメントの作成を簡素化することです。
最小限の構成で、MkDocs は Markdown ファイルをナビゲート可能で適切に構造化されたドキュメント Web サイトに変換するため、ドキュメントを最新の状態に保ちたい開発者やチームにとって理想的です。
MkDocs マテリアル は、Google のマテリアル デザイン ガイドラインに準拠した MkDocs の高度なテーマです。
Mermaid は、テキストから図やチャートを作成するための JavaScript ライブラリです。 MkDocs マテリアルと統合することで、Mermaid を使用すると、外部ツールを使用せずに、ドキュメント内でフローチャート、エンティティ関係図、その他のチャートなどの視覚化を生成できます。
Jinja は、Python 辞書の変数とデータを HTML に埋め込み、Web ページを動的にするライブラリです。このライブラリは、動的 HTML の生成とパーソナライズされた電子メールの送信によく使用されます。
Docusaurus は、2007 年に Meta によって開発されたオープンソース プロジェクトで、ドキュメント Web サイトの作成、展開、保守を迅速かつ効率的な方法で簡素化します。 Markdown と MDX を使用してコンテンツを作成できるほか、React 上に構築されたコアにより、プロジェクトの特定のニーズに合わせてスタイルを完全にカスタマイズできます。
さらに、Docusaurus は @docusaurus/theme-mermaid プラグインを通じて Mermaid をサポートしており、ドキュメント内にチャートや図を直接組み込むことができます。
Diagram as Code は、従来のグラフィック ツールを使用するのではなく、コードを通じて図を作成できるアプローチです。図を手動で構築する代わりに、テキスト ファイルにコードを記述して、図の構造、コンポーネント、接続を定義します。
このコードはグラフィック イメージに変換されるため、ソフトウェア プロジェクトへの統合と文書化が容易になります。これは、アーキテクチャ図やフロー図をプログラムで作成および更新する場合に特に役立ちます。
前述したように、ダイアグラム を使用すると、主要なクラウド テクノロジーのアイコンを使用してブループリントを生成できます。これらの図の表現はノードを通じて行われ、この例ではすべてのクラウド関連のノードと AWS サービスを使用します。
これを作成した方法の詳細については、Diagram as Code に関する私の記事を参照してください。完全な実装はこのリポジトリにあります。
r0マイメンデス
/
コードとしての図
Diagram as Code は、従来のグラフィック ツールの代わりにコードを使用して図を作成できるアプローチです。図を手動で構築する代わりに、テキスト ファイルにコードを記述して、図の構造、コンポーネント、接続を定義できます。
このコードはグラフィカル イメージに変換されるため、ソフトウェア プロジェクトへの統合と文書化が容易になります。特に、アーキテクチャ図やフロー図をプログラムで作成および更新する場合に役立ちます。
Diagrams は、Diagram as Code アプローチを実装する ?Python ライブラリ で、コードを通じてアーキテクチャ インフラストラクチャ ダイアグラムや他のタイプのダイアグラムを作成できるようにします。図を使用すると、わずか数行のコードでクラウド インフラストラクチャ コンポーネント (AWS、Azure、GCP など)、ネットワーク要素、ソフトウェア サービスなどを簡単に定義できます。
このユースケースでは、? を含む機械学習プロジェクトのドキュメント サイトを作成します。病院のデータ。目標は、最初に MkDocs を使用してインタラクティブなドキュメント サイトを構築し、後でそれを Docusaurus に移行することです。このサイトには、ビジュアル ダイアグラムの埋め込みや SQLite データベースからのデータの動的更新など、特定の要件を満たす静的コンポーネントと動的コンポーネントの両方が含まれます。
このため、ドキュメント サイトには次のページがあります:
このセクションでは、MkDocs を使用してドキュメント プロジェクトを最初からセットアップする手順を説明し、その整理されたディレクトリ構造について説明します。
始めるには、次の ?Python ライブラリをインストールする必要があります:
MkDocs とマテリアルをインストールします
pip install mkdocs mkdocs-material
追加のライブラリをインストールして動的コンテンツ更新を有効にします
pip install aiosql pandas sqlite3 jinja2 shutil
プロジェクトを初期化する
新しい MkDocs プロジェクトを作成することから始めます。ターミナルで次のコマンドを実行します:
mkdocs new mkdocs cd mkdocs
このコマンドは、デフォルトの構造を持つ基本的な MkDocs プロジェクトを作成します。
ディレクトリ構造を調べる
MkDocs サイトが作成されたら、次のファイルとフォルダーはデフォルトでは含まれていないため、追加する必要があります。
参照用にこの投稿の最後にリポジトリへのリンクが記載されていることに注意してください。各コンポーネントについては以下で詳しく説明します。
pip install mkdocs mkdocs-material
| Component | Directory | Description |
|---|---|---|
| Database (db) | db | Contains the SQLite database (hospital.db) and queries (metadata.sql, person.sql) to manage dynamic data. Learn more about managing SQL queries in Python in my previous article: Python Projects with SQL. |
| ?️ Templates & Pages | template | Markdown templates: index.md, tables.md, architecture.md, glossary.md. Supports Mermaid diagrams, embedded images, and database-driven content. |
| ?️ Static Content (docs) | docs | Final site generated by update.py, including images (img/) and dynamic content populated from template. |
| ? Infrastructure (infraestructure) | infraestructure | Terraform scripts (main.tf, variables.tf) to deploy an S3 bucket for documentation hosting. |
プロジェクト構造を設定したら、mkdocs.yml ファイルから始めて、段階的に構成していきます。このファイルは、ドキュメント サイトの構造と設定を定義します。どのように構成する必要があるかは次のとおりです:
mkdocs.yml
pip install mkdocs mkdocs-material
この 設定ファイル では、主に nav セクションでメニューからアクセスできるページを確認できます。次に、次のセクションで説明する Mermaid 拡張機能を指定します。最後に、テーマ セクションではマテリアル テーマを適用し、このライブラリ内で使用できるスタイルとコンポーネントを有効にします。
前述したように、Mermaid は、テキストから図やチャートを作成するための JavaScript ライブラリです。以下にいくつかの例を示します。この例では、これを使用して、ドキュメントの テーブル ページでエンティティ関係図 (ERD) を生成します。
リポジトリでは、Synthea の公式ドキュメントにあるエンティティ関係図 (ERD) に基づいてこのコードを構築する方法を確認できます。次のリンクでテーブル ページの例を確認することもできます: tables.md.
ドキュメント サイトの動的コンテンツ生成を有効にするために、Jinja を使用してテンプレートを処理し、プレースホルダーを実際のデータに置き換えます。以下は段階的な内訳です:
テンプレートフォルダーをセットアップする
サイトのすべての Markdown ファイルを保存するための template という名前のフォルダーを作成します。これらのファイルにはプレースホルダーが含まれている必要があります。たとえば、index.md には、{{database.version_date}} や {{database.version}} のようなプレースホルダーがある場合があります。
プレースホルダーを使用する
プレースホルダーは、Markdown ファイル内の動的変数です。これらの変数は、Python 辞書を使用して関連データを挿入することで自動的に更新されます。
update.py を使用して動的コンテンツを生成する
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
これらの手順に従うことで、ドキュメント サイトの更新プロセスを自動化し、手動で編集しなくてもコンテンツが動的かつ関連性を維持できるようにすることができます。
次の例では、tables.md ファイルの内容を更新して、データベースの persons テーブルの例を示します。これを行うには、Markdown ファイル内にプレースホルダー {{table.person}} を作成します。そのアイデアは、persons テーブルからデータを動的にフェッチし、Jinja ライブラリと pandas を使用してクエリ結果を Markdown テーブル形式に変換することです。
プレースホルダーを使用した tables.md ファイルの例を次に示します。
mkdocs new mkdocs cd mkdocs
プロセスは次のとおりです:
? 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
このようにして、ドキュメントには常に最新のデータが反映され、データベースの実際のコンテンツに基づいた動的な例が表示されます。
次のセクションでは、Docusaurus を使用してドキュメント サイトを実装する方法について、詳細な手順と洞察を提供します。これには、セットアップ、カスタマイズ、展開オプションが含まれます。
Docusaurus を使い始めるには、簡単なセットアップ プロセスに従います。これは MkDocs で使用した手順とよく似ていますが、ツールが異なります。
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
mkdocs new mkdocs cd mkdocs
構成ファイル docusaurus.config.js で、タイトル、テーマ、ナビゲーションをカスタマイズし、図のレンダリング用に Mermaid などの機能を有効にします。
Mermaid を有効にするためのスニペットの例:
pip install mkdocs mkdocs-material
ホームページをカスタマイズするには、src/components/Homepage features/index.js ファイルを変更します。ここで、FeatureList オブジェクトを調整して、ホームページに表示される機能を更新できます。
MkDocs と同様に、Docusaurus はコンテンツの Markdown ファイル をサポートしており、次のように構造を編成します。
pip install aiosql pandas sqlite3 jinja2 shutil
__category__.json の例:
mkdocs new mkdocs cd mkdocs
データベース テーブルなどの動的コンテンツを組み込むには、リポジトリにある update.py という名前の ?Python スクリプトを使用します。
このスクリプトは、SQLite データベースからデータを取得し、テンプレート フォルダーに保存されている Markdown ファイルを処理します。次に、取得したデータでこれらのファイルを更新し、docs フォルダーにコピーして、サイトのレンダリングの準備をします。
このワークフローは、MkDocs で実装したものと同様のアプローチに従って、コンテンツを最新の状態に保ち、展開の準備ができていることを保証します。
このセクションでは、AWS S3 をホスティングに使用した MkDocs と Docusaurus の両方の デプロイメントプロセス について説明します。どちらのツールでも展開手順は同じですが、MkDocs は Python ベースであり、Docusaurus は JavaScript ベースであるため、インストール プロセスが異なります。
静的ドキュメント サイトを AWS S3 にデプロイするには、Terraform を使用して必要なリソースをプロビジョニングおよび構成します。このセットアップでは、S3 バケットを定義し、静的 Web サイト ホスティングを有効にし、バケット ポリシーを使用して読み取り専用アクセスを許可するパブリック アクセスを構成します。 main.tf ファイルはリポジトリにあります。
完全な Terraform ファイル と、リポジトリにサイトをデプロイするための対応する構成にアクセスできます。
Terraform 構成ファイル:
自動デプロイのための GitHub アクション ワークフロー: デプロイ プロセスを自動化する CI/CD パイプラインもリポジトリに含まれています。
GitHub アクションの構成
設定 > の GitHub リポジトリ シークレット で AWS 認証情報を必ず設定してください。 秘密 > アクション。これにより、GitHub Actions が AWS アカウントに安全にアクセスし、変更をメイン ブランチにプッシュするときに S3 へのファイルのアップロードなどのアクションを実行できるようになります。
以下は、ドキュメント サイトを展開するためのすべてのコードへのリンクです。役に立ったと思ったら、スター⭐️を付けてフォローしていただくと、新しい記事の通知が届きます。これは、テクノロジー コミュニティで成長し、より多くのコンテンツを作成するのに役立ちます。
r0マイメンデス
/
コードとしてのドキュメント-mkdocs
MkDocs は、コードで簡単に更新できるドキュメント ポータルを実装するための優れたソリューションであり、ソフトウェア開発プロジェクトのドキュメントを最新のバージョンに保つのに役立ちます。
このリポジトリに、データ モデルと機械学習プロジェクトを文書化するための簡単なサイトを作成しました。
ドキュメントにはチャート、表、アーキテクチャの例が含まれており、他の 2 つの ?Python ライブラリと組み合わせてこのフレームワークを実装する方法について包括的でわかりやすいガイドが提供されます。
ドキュメントとその更新は、ソフトウェアを開発する多くの企業にとって重要なプロセスであり、このプロセスはさまざまなツールを使用して実行され、その多くは有料ソリューションです。
したがって、最近では、「doc as code」 という概念が登場しました。これは、ソフトウェア開発で使用されるのと同じツールとワークフローを使用して、管理、バージョン管理、および…
r0マイメンデス
/
ドキュメントとしてのコード-ドキュサウルス
Docusaurus は、コードで簡単に更新できるドキュメント ポータルを実装するための優れたソリューションであり、ソフトウェア開発プロジェクトのドキュメントを最新のバージョンに保つのに役立ちます。
このリポジトリに、データ モデルと機械学習プロジェクトを文書化するための簡単なサイトを作成しました。
ドキュメントにはチャート、表、アーキテクチャの例が含まれており、他の 2 つの ?Python ライブラリと組み合わせてこのフレームワークを実装する方法について包括的でわかりやすいガイドが提供されます。
ドキュメントとその更新は、ソフトウェアを開発する多くの企業にとって重要なプロセスであり、このプロセスはさまざまなツールを使用して実行され、その多くは有料ソリューションです。
したがって、最近では、「doc as code」 という概念が登場しました。これは、ソフトウェア開発で使用されるのと同じツールとワークフローを使用して、ドキュメントの管理、バージョン付け、展開を行うことを意味します…
どちらのソリューションも実装は簡単ですが、次の項目でいくつかの違いを検討します。最適なソリューションはどれであるかは、実装する必要があるコンテキスト、知識、複雑さによって異なります。
以上がAWS での Docs-as-Code のデプロイ: MkDocs と Docusaurus での動的なドキュメント サイトの構築の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。
![[Web フロントエンド] Node.js クイック スタート](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
