Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 12521] ファイルの概要

このコミットは、Go言語の公式ドキュメント生成および提供ツールであるgodocの機能拡張と、それに伴うドキュメントのビルドプロセスの変更に関するものです。具体的には、godocがテンプレートを直接処理してHTMLを生成する機能が追加され、これまで外部ツールであったtmpltohtmlが不要になりました。これにより、ドキュメントのビルドプロセスが簡素化され、godoc自体がドキュメントのレンダリングを一元的に担うようになりました。

コミット

commit a40065ac6838068f07dcb12084406bab403067f2
Author: Russ Cox <rsc@golang.org>
Date:   Thu Mar 8 08:39:20 2012 -0500

    cmd/godoc: add support for serving templates
    doc: convert to use godoc built-in templates
    
    tmpltohtml is gone, to avoid having a second copy of the code.
    Instead, godoc -url /doc/go1.html will print the actual HTML
    served for that URL.  "make" will generate files named go1.rawhtml
    etc, which can be fed through tidy.
    
    It can be hard to tell from the codereview diffs, but all the
    tmpl files have been renamed to be html files and then
    have "Template": true added.
    
    R=golang-dev, adg, r, gri
    CC=golang-dev
    https://golang.org/cl/5782046

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/a40065ac6838068f07dcb12084406bab403067f2

元コミット内容

このコミットの元々の内容は以下の通りです。

  • cmd/godoc: テンプレートを提供する機能を追加。
  • doc: godocの組み込みテンプレートを使用するように変換。
  • tmpltohtmlツールは、コードの重複を避けるために廃止されました。
  • 代わりに、godoc -url /doc/go1.htmlを実行すると、そのURLで提供される実際のHTMLが出力されるようになります。
  • makeコマンドは、go1.rawhtmlなどのファイルを生成し、これらはtidyコマンドで整形できます。
  • コードレビューの差分からは分かりにくいかもしれませんが、全ての.tmplファイルが.htmlファイルにリネームされ、"Template": trueというメタデータが追加されています。

変更の背景

この変更の背景には、Go言語のドキュメント生成プロセスにおける効率化と一貫性の向上が挙げられます。

  1. コードの重複排除: 以前は、Goのドキュメント（特に記事やチュートリアル）は.tmplファイルとして記述され、tmpltohtmlという別のツールを使ってHTMLに変換されていました。このtmpltohtmlは、godocが内部で使用しているテンプレートエンジンと類似のロジックを持っていたため、コードの重複が発生していました。このような重複は、メンテナンスの複雑さを増し、将来的な機能追加やバグ修正の際に二重の作業を必要とする可能性がありました。
  2. ビルドプロセスの簡素化: tmpltohtmlという中間ツールを廃止し、godoc自体がテンプレートのレンダリングを直接行えるようにすることで、ドキュメントのビルドプロセスが簡素化されます。これにより、Makefileなどのビルドスクリプトもよりシンプルになり、開発者の負担が軽減されます。
  3. godocの一元化: godocはGoのコードドキュメントを生成・表示するための主要なツールです。このツールにドキュメントのテンプレート処理機能も統合することで、Goのドキュメントに関する全ての処理をgodocに一元化し、ツールの役割を明確にするとともに、全体的なエコシステムの一貫性を高める狙いがあります。
  4. 動的なコンテンツ生成への対応: godocが直接テンプレートを処理できるようになることで、将来的にはより動的なコンテンツや、サーバーサイドでのリアルタイムなドキュメント生成・表示といった機能拡張への道が開かれます。

前提知識の解説

このコミットを理解するためには、以下の前提知識が必要です。

  1. Go言語のtext/templateおよびhtml/templateパッケージ:

    • Go言語には、テキストやHTMLを生成するためのテンプレートエンジンが標準ライブラリとして提供されています。
    • text/templateは汎用的なテキスト生成に、html/templateはHTMLの生成に特化しており、クロスサイトスクリプティング（XSS）攻撃を防ぐための自動エスケープ機能を持っています。
    • これらのテンプレートは、{{.FieldName}}のようなプレースホルダーや、{{range .Items}}...{{end}}のような制御構造、{{if .Condition}}...{{end}}のような条件分岐などを用いて、動的にコンテンツを生成します。
    • godocは、これらのテンプレートエンジンを利用して、Goのソースコードから抽出した情報（型、関数、変数、コメントなど）を整形して表示します。

  2. godocツール:

    • godocは、Go言語のソースコードからドキュメントを生成し、Webサーバーとして提供するツールです。
    • 開発者がコードに記述したコメント（特にエクスポートされた要素に対するコメント）を解析し、Goの標準的なドキュメント形式に変換して表示します。
    • 通常、godoc -http=:8000のように実行することで、ローカルでドキュメントサーバーを立ち上げることができます。
    • このコミット以前は、godocは主にコードドキュメントの表示に特化しており、Goの公式ウェブサイトに掲載されるような記事やチュートリアル（.tmplファイルで書かれたもの）は、別のツールでHTMLに変換する必要がありました。

  3. tmpltohtmlユーティリティ（廃止前）:

    • このコミットで廃止されたtmpltohtmlは、Goのドキュメントリポジトリ内で使用されていたカスタムツールです。
    • .tmpl拡張子を持つテンプレートファイルを読み込み、それをHTMLファイルに変換する役割を担っていました。
    • これは、godocが直接テンプレートを処理する機能を持っていなかったための中間ステップでした。

  4. Makefile:

    • Makefileは、ソフトウェアのビルドプロセスを自動化するためのスクリプトファイルです。
    • makeコマンドによって実行され、ファイルの依存関係に基づいてコマンドを実行します。
    • このコミットでは、Makefile内のtmpltohtmlの呼び出しが削除され、代わりにgodoc -urlコマンドが使用されるように変更されています。

  5. Goのドキュメントにおける{{code}}ディレクティブ:

    • Goの公式ドキュメントや記事では、コード例を埋め込むために{{code "path/to/file.go" "/start_regex/" "/end_regex/"}}のような特殊なディレクティブが使用されていました。
    • これは、指定されたGoソースファイルから、正規表現で指定された範囲のコードを抽出し、ドキュメント内に表示するためのものです。
    • このコミットでは、このディレクティブのパス指定が変更され、godocが内部で解決できるように調整されています。

技術的詳細

このコミットの技術的な変更点は多岐にわたりますが、主要なものは以下の通りです。

  1. godocへのテンプレートサービング機能の追加:

    • src/cmd/godoc/main.goおよびsrc/cmd/godoc/doc.goに、HTTPリクエストに応じてGoテンプレートをレンダリングするロジックが追加されました。
    • これにより、godocは単にGoコードのドキュメントを生成するだけでなく、特定のURLパス（例: /doc/go1.html）に対するリクエストを受け取った際に、対応するテンプレートファイルを読み込み、動的にHTMLを生成して返すことができるようになりました。
    • 特に、godoc -url <path>コマンドが導入され、指定されたパスに対応するHTMLコンテンツを標準出力に出力できるようになりました。これは、ビルドプロセスで静的なHTMLファイルを生成するために利用されます。

  2. .tmplファイルから.htmlファイルへの移行とメタデータの追加:

    • doc/articles/やdoc/直下にあった.tmpl拡張子のファイル（例: effective_go.tmpl, go1.tmpl）が、対応する.html拡張子のファイルにリネームされました。
    • これらの新しい.htmlファイルの先頭には、JSON形式のメタデータブロックが追加されました。例えば、<!--{"Title": "Defer, Panic, and Recover", "Template": true}-->のように、"Template": trueというキーが追加されています。
    • この"Template": trueというフラグは、godocがこのHTMLファイルを単なる静的なHTMLとしてではなく、内部のテンプレートエンジンで処理すべきテンプレートとして認識するためのマーカーとなります。これにより、{{code}}などの特殊なディレクティブが適切に解釈・展開されるようになります。

  3. tmpltohtml.goの廃止とsrc/cmd/godoc/template.goへの統合:

    • 以前は独立したツールであったdoc/tmpltohtml.goが削除されました。
    • その機能はsrc/cmd/godoc/template.goとしてgodocの内部に統合されました。これは、godocがテンプレートを直接処理する能力を獲得したことを意味します。
    • この統合により、テンプレートの解析、コード例の埋め込み（{{code}}ディレクティブの処理）、HTMLの生成といったロジックがgodocのコードベース内で一元管理されることになります。

  4. Makefileの変更:

    • doc/Makefileが大幅に簡素化されました。
    • tmpltohtmlのビルドと実行に関するルールが削除されました。
    • 代わりに、.rawhtmlファイルを生成するための新しいルールが追加されました。このルールは、godoc -url /doc/$* >$@というコマンドを実行し、godoc自身にHTMLコンテンツを生成させています。
    • 生成されるファイル名も.htmlから.rawhtmlに変更され、これはtidyなどの後処理を前提としていることを示唆しています。

  5. {{code}}ディレクティブのパス解決の変更:

    • ドキュメント内の{{code}}ディレクティブのパス指定が、progs/defer.goのような相対パスから/doc/progs/defer.goのような絶対パス（godocのURLパスとしての）に変更されました。
    • これは、godocがWebサーバーとして動作する際に、これらのパスを適切に解決して対応するコードスニペットを埋め込むためです。

これらの変更により、Goのドキュメント生成は、外部ツールへの依存を減らし、godocを中心としたより統合された、効率的なワークフローへと移行しました。

コアとなるコードの変更箇所

このコミットにおけるコアとなるコードの変更箇所は以下のファイルに集中しています。

  1. doc/Makefile:

    • tmpltohtmlのビルドと実行に関する行が削除されました。
    • HTML変数がRAWHTMLに変更され、生成されるファイル名が.htmlから.rawhtmlに変わりました。
    • %.html: %.tmpl tmpltohtmlというルールが削除され、代わりに%.rawhtml: %.htmlという新しいルールが追加されました。この新しいルールでは、godoc -url /doc/$* >$@が実行され、godoc自身がHTMLを生成するようになりました。

  2. doc/articles/*.html および doc/*.html ファイル群:

    • defer_panic_recover.tmpl -> defer_panic_recover.html など、全ての.tmplファイルが対応する.htmlファイルにリネームされました。
    • リネームされた各.htmlファイルの先頭に、<!--{"Title": "...", "Template": true}-->という形式のJSONメタデータブロックが追加されました。特に"Template": trueが重要です。
    • ファイル内の<!--{{code "..."}}-->形式のコメントが削除され、{{code "..."}}という直接的なテンプレートディレクティブに置き換えられました。また、{{code}}ディレクティブ内のパスが、progs/defer.goのような相対パスから/doc/progs/defer.goのようなgodocのURLパス形式に変更されました。

  3. doc/tmpltohtml.go:

    • このファイル自体が完全に削除されました。

  4. src/cmd/godoc/doc.go:

    • godocがドキュメントを処理する際のロジックが変更され、新しいテンプレート処理機能が組み込まれました。
    • 特に、godocが"Template": trueメタデータを持つHTMLファイルをテンプレートとして認識し、内部でレンダリングするための変更が含まれています。

  5. src/cmd/godoc/godoc.go:

    • godocのメインロジックに、テンプレートサービングに関連する新しいハンドラや設定が追加された可能性があります。

  6. src/cmd/godoc/main.go:

    • godocコマンドラインツールのエントリポイントであり、新しい-urlフラグの処理や、テンプレートサービング機能の初期化に関する変更が含まれています。

  7. doc/tmpltohtml.go => src/cmd/godoc/template.go:

    • これはファイルのリネームと移動を示しており、tmpltohtmlの機能がgodocの内部モジュールとしてsrc/cmd/godoc/template.goに統合されたことを意味します。このファイルには、テンプレートの解析、コードスニペットの埋め込みなどのロジックが含まれています。

これらの変更は、Goのドキュメント生成と提供のアーキテクチャを根本的に変更し、godocをより強力で汎用的なドキュメントツールへと進化させました。

コアとなるコードの解説

このコミットの核心は、godocがGoのドキュメントを生成する際の「テンプレートエンジン」としての役割を強化した点にあります。

以前は、Goのドキュメント（特に記事やチュートリアル）は.tmplファイルとして書かれ、tmpltohtmlという外部ツールによって静的なHTMLファイルに変換されていました。この変換プロセスでは、{{code "..."}}のような特殊なディレクティブが、実際のGoソースコードスニペットに置き換えられていました。

このコミットでは、このtmpltohtmlの機能をgodoc自体に組み込みました。

  1. doc/Makefileの変更:

    • 最も分かりやすい変更はMakefileです。以前はtmpltohtmlを実行して.tmplファイルを.htmlに変換していましたが、新しいMakefileではgodoc -url /doc/$* >$@というコマンドを使っています。
    • これは、godocに対して特定のURLパス（例: /doc/go1.html）に対応するHTMLコンテンツを生成し、それを標準出力に書き出すように指示しています。この出力が.rawhtmlファイルとして保存されます。
    • この変更により、ドキュメントのビルドパイプラインからtmpltohtmlという中間ステップが完全に削除されました。

  2. ドキュメントファイルの変更（.tmplから.htmlへ、メタデータの追加）:

    • 全てのドキュメントファイルが.tmplから.htmlにリネームされました。これは、これらのファイルが最終的にHTMLとして提供されることを明確にするためです。
    • 重要なのは、これらの新しい.htmlファイルの先頭に<!--{"Title": "...", "Template": true}-->というJSON形式のコメントが追加されたことです。
      • "Title"はドキュメントのタイトルを示します。
      • "Template": trueというキーは、godocに対して「このHTMLファイルは単なる静的なHTMLではなく、内部のテンプレートエンジンで処理すべきテンプレートである」と明示的に伝えます。
    • これにより、godocはこれらのファイルを読み込んだ際に、通常のHTMLとしてではなく、Goのhtml/templateパッケージで処理されるべきテンプレートとして扱います。

  3. godoc内部の変更（template.goへの統合と処理ロジック）:

    • tmpltohtml.goのコードがsrc/cmd/godoc/template.goとしてgodocの内部に移動・統合されました。
    • このtemplate.goには、Goのテンプレートエンジン（html/template）を使用して、ドキュメントファイル内の{{code "..."}}ディレクティブを実際のGoソースコードスニペットに置き換えるロジックが含まれています。
    • godocがWebサーバーとして動作する際、/doc/以下のパスへのリクエストを受け取ると、対応する.htmlファイルを読み込み、そのメタデータ（"Template": true）をチェックします。
    • もし"Template": trueが設定されていれば、godocはファイルの内容をテンプレートとして解析し、{{code}}ディレクティブを解決して、最終的なHTMLを生成してクライアントに返します。
    • godoc -urlコマンドも同様に、内部のテンプレート処理ロジックを利用してHTMLを生成します。

この一連の変更により、Goのドキュメントは、godocという単一のツールによって、ソースコードのドキュメント生成から、記事やチュートリアルのテンプレート処理、そして最終的なHTMLの提供まで、一貫して管理されるようになりました。これにより、ビルドプロセスが簡素化され、コードの重複が解消され、Goのドキュメントエコシステム全体がより堅牢でメンテナンスしやすくなりました。

関連リンク

参考にした情報源リンク