このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソースの組織:
- Cloud Native Computing Foundation（CNCF）
- テクニカル ライター:
- feloy
- プロジェクト名:
- Kubernetes ウェブサイトで API リファレンスを提供する方法を更新
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
現在、Kubernetes API リファレンスは、ウェブサイト リポジトリの外部でホストされているスクリプトによって Swagger 仕様から生成され、このウェブサイト リポジトリに追加された大規模な HTML ドキュメントです。
一方、Kubernetes ドキュメント ウェブサイトは、Docsy Hugo テーマを使用して、ウェブサイト リポジトリに Markdown 形式で記述されたドキュメントから Hugo で構築されています。
このプロジェクトの目標は、Kubernetes API リファレンスの生成を、ドキュメント ウェブサイトをビルドするプロセスに統合することです。
具体的には、Docsy Hugo テーマで提供される swagger-ui をラップする swaggerui ショートコードと、Kubernetes ドキュメントのフローに API 仕様の一部を挿入できる特定のツールについて説明します。
swagger-ui は、Swagger ファイルに記述されている仕様全体を出力できますが、その一部を出力することはできません（8 を参照）。そのため、特定のツールが必要になります。Kubernetes API は大きすぎて、1 つの部分にのみ表示することはできません（出力の例）。ここでは、次の 2 つのアプローチを検討します。
1 つ目の方法は、(10) にあるソースから Kubernetes API グループ（core/v1、apps/v1 など）ごとに複数の Swagger ファイルを作成し、そのファイルを Kubernetes ドキュメント ウェブサイトの特定の場所で swaggerui ソートコードの入力として使用することです。
2 つ目のアプローチは、（11）にある Kubernetes API の完全な Swagger ファイルを入力として取得し、特定のエンドポイントまたは限られた数のエンドポイント、および関連するリソースと定義の新しい Swagger ファイルを出力し、それらの Swagger ファイルを Kubernetes ドキュメントのウェブサイトの特定の場所で swaggerui ショートコードの入力として使用することです。
仕様のソース（10 と 11）はドキュメントのソースとは異なるリポジトリに存在するため、変更があったときにドキュメント リポジトリで自動的に更新する方法を見つける必要があります。
Kubernetes のドキュメントはさまざまな言語で提供されているため、Kubernetes API リファレンスの翻訳を公開する可能性に特に注意を払っています。