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