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

このコミットは、Go言語の公式ドキュメントツールであるgodocに、ナビゲーションバーからアクセスできるドロップダウン形式のGo Playgroundを追加するものです。これにより、ユーザーはドキュメントを閲覧しながら、その場でGoコードを試すことができるようになり、学習体験と利便性が向上します。

コミット

commit 84386416294922b948e91ebc3226271c1d049998
Author: Andrew Gerrand <adg@golang.org>
Date:   Wed Oct 10 11:17:47 2012 +1100

    godoc: add dropdown playground to nav bar

    R=gri, dsymonds, skybrian
    CC=golang-dev
    https://golang.org/cl/6631057

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

https://github.com/golang/go/commit/84386416294922b948e91ebc3226271c1d049998

元コミット内容

godoc: add dropdown playground to nav bar

R=gri, dsymonds, skybrian
CC=golang-dev
https://golang.org/cl/6631057

変更の背景

Go言語の公式ドキュメントツールであるgodocは、Goのソースコードから自動的にドキュメントを生成し、ウェブブラウザで閲覧可能にする非常に便利なツールです。一方、Go Playgroundは、ブラウザ上でGoコードを記述、実行、共有できるインタラクティブな環境を提供します。

このコミットの背景には、ユーザーがgodocでドキュメントを読みながら、その場でコードの動作を確認したいというニーズがあったと考えられます。以前は、コード例を試すにはGo Playgroundのサイトに別途アクセスする必要がありましたが、この変更により、godocのナビゲーションバーから直接Playground機能にアクセスできるようになり、ユーザーエクスペリエンスが大幅に向上しました。これにより、ドキュメントと実践的なコード実行の間の障壁が取り除かれ、Go言語の学習と理解がよりスムーズになることが期待されます。

前提知識の解説

• godoc: Go言語のソースコードからドキュメントを生成し、HTTPサーバーとして提供するツールです。Goの標準ライブラリやサードパーティライブラリのドキュメント閲覧に広く利用されています。Goのコードコメント（特にエクスポートされた識別子に対するコメント）を解析し、HTML形式で整形して表示します。
• Go Playground: Go言語のコードをブラウザ上で記述、実行、共有できるウェブサービスです。サーバーサイドでGoコードをコンパイル・実行し、その結果をブラウザに返します。これにより、ローカルにGo環境をセットアップすることなく、手軽にGoコードを試すことができます。また、コードの共有機能も提供しており、Goコミュニティでのコードスニペットの共有によく利用されます。
• HTML (HyperText Markup Language): ウェブページの構造を定義するためのマークアップ言語です。要素（タグ）を使って、見出し、段落、リンク、画像などを配置します。
• CSS (Cascading Style Sheets): ウェブページの見た目（スタイル）を定義するためのスタイルシート言語です。色、フォント、レイアウトなどを指定し、HTML要素の表示を制御します。
• JavaScript: ウェブページに動的な機能を追加するためのプログラミング言語です。ユーザーの操作に応じたインタラクション、コンテンツの動的な変更、非同期通信などを実現します。
• jQuery: JavaScriptライブラリの一つで、HTML要素の選択、操作、イベント処理、アニメーション、Ajax通信などを簡潔に記述できるようにします。DOM操作を容易にし、ブラウザ間の互換性の問題を吸収します。
• DOM (Document Object Model): HTMLやXMLドキュメントの構造を、プログラムからアクセス・操作できるようにするためのAPIです。JavaScriptからDOMを操作することで、ウェブページのコンテンツやスタイルを動的に変更できます。

技術的詳細

このコミットは、godocのフロントエンド（HTML、CSS、JavaScript）とバックエンド（Go）の両方に変更を加えて、ドロップダウン形式のGo Playgroundを統合しています。

1. JavaScript (doc/godocs.js) の変更:

   • setupDropdownPlayground関数が新しく追加されました。この関数は、ナビゲーションバーの「Play」ボタンと、ドロップダウンとして表示されるPlayground領域の挙動を制御します。
   • ボタンのクリックイベントをtoggle関数でバインドし、クリックするたびにPlaygroundの表示/非表示を切り替えます。
   • Playgroundが初めて表示される際に、playground関数（playground.jsで定義されているGo Playgroundのコア機能）を初期化します。この初期化では、コード入力エリア、出力エリア、実行ボタン、フォーマットボタン、共有ボタンなどのDOM要素をplayground関数に渡します。
   • shareRedirectとしてhttp://play.golang.org/p/が設定されており、共有機能がGo Playgroundの公式URLにリダイレクトされるようになっています。
   • $(document).ready関数内でsetupDropdownPlayground()が呼び出され、ページロード時にこの機能が初期化されるようになっています。
   • #menuのmin-widthを調整し、新しい「Play」ボタンが追加されてもレイアウトが崩れないようにしています。

2. CSS (doc/style.css) の変更:

   • ドロップダウンPlaygroundのスタイルと位置を定義する新しいCSSルールが追加されました。
   • #playgroundButtonとdiv#playgroundは初期状態でdisplay: none;となっており、JavaScriptによって表示が制御されます。
   • div#playgroundはposition: absolute;とtop, rightプロパティを使用して、ナビゲーションバーの右下にドロップダウンとして表示されるように配置されます。z-index: 1;で他の要素の上に表示されるようにしています。
   • 背景色、ボーダー、角丸などのスタイルが適用され、視覚的に統合された外観を提供します。
   • div#playground .codeとdiv#playground .outputのサイズが指定され、ドロップダウン内のコードエディタと出力エリアのレイアウトを調整しています。
   • @mediaクエリが追加され、特定の画面幅（min-width: 130ex）以上の場合に、div#topbar.wideとdiv#page.wideがposition: fixed;となり、トップバーが固定され、ページコンテンツがその下にスクロール可能になるように調整されています。これは、広い画面でのレイアウトの改善を目的としています。

3. HTML (lib/godoc/godoc.html) の変更:

   • Go Playgroundのコア機能を提供するplayground.jsが、.Playground変数がtrueの場合にのみ読み込まれるように条件付きで追加されました。これにより、Playground機能が不要なページでは余分なスクリプトのロードを避けることができます。
   • ナビゲーションバー（div#menu内）に「Play」ボタン（id="playgroundButton"）が追加されました。このボタンも.Playground変数がtrueの場合にのみ表示されます。
   • ドロップダウンとして表示されるPlaygroundのHTML構造（div#playground）が追加されました。これには、コード入力用のtextarea、出力表示用のdiv、そして「Run」「Format」「Share」ボタンが含まれています。初期コードとして"Hello, 世界"を出力する簡単なGoプログラムが設定されています。このdiv#playground全体も.Playground変数の値に基づいて条件付きでレンダリングされます。
   • div#topbarとdiv#pageのクラス属性の適用方法が変更され、wideクラスがcontainer要素ではなく、親のtopbarやpage要素に直接適用されるようになりました。これにより、CSSのセレクタと整合性が取られています。
   • div#page内のコンテンツがdiv.containerでラップされるように変更され、全体的なレイアウト構造が改善されています。

4. HTML (lib/godoc/package.html) の変更:

   • playground.jsの読み込みが削除されました。これは、godoc.htmlで一元的に管理されるようになったためです。これにより、重複読み込みが避けられます。

5. Go (src/cmd/godoc/godoc.go) の変更:

   • Page構造体にPlaygroundという新しいブール型フィールドが追加されました。このフィールドは、HTMLテンプレートでGo Playground関連の要素を表示するかどうかを制御するために使用されます。
   • servePage関数内で、page.Playgroundが*showPlaygroundというグローバル変数（おそらくコマンドライン引数などで設定される）の値に基づいて設定されるようになりました。これにより、サーバーサイドでPlayground機能の有効/無効を制御できるようになります。

これらの変更により、godocは単なるドキュメントビューアから、インタラクティブなコード実行環境を内包する、よりリッチな学習プラットフォームへと進化しました。

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

• doc/godocs.js: setupDropdownPlayground関数の追加と、$(document).readyでの呼び出し。
• doc/style.css: #playgroundButton, div#playgroundおよびその内部要素のスタイル定義、@mediaクエリによるレスポンシブデザインの調整。
• lib/godoc/godoc.html: 「Play」ボタンとドロップダウンPlaygroundのHTML構造の追加、playground.jsの条件付き読み込み。
• lib/godoc/package.html: playground.jsの読み込みの削除。
• src/cmd/godoc/godoc.go: Page構造体へのPlaygroundフィールドの追加と、servePage関数でのその値の設定。

コアとなるコードの解説

doc/godocs.js の setupDropdownPlayground 関数

function setupDropdownPlayground() {
  if (!$('#page').is('.wide')) {
    return; // don't show on front page
  }
  var button = $('#playgroundButton');
  var div = $('#playground');
  var setup = false;
  button.toggle(function() {
    button.addClass('active');
    div.show();
    if (setup) {
      return;
    }
    setup = true;
    playground({
      'codeEl': $('.code', div),
      'outputEl': $('.output', div),
      'runEl': $('.run', div),
      'fmtEl': $('.fmt', div),
      'shareEl': $('.share', div),
      'shareRedirect': 'http://play.golang.org/p/'
    });
  },
  function() {
    button.removeClass('active');
    div.hide();
  });
  button.show();
  $('#menu').css('min-width', '+=60');
}

このJavaScript関数は、ドロップダウンPlaygroundのインタラクティブな挙動を定義します。

• if (!$('#page').is('.wide')) { return; }: フロントページ（.wideクラスがないページ）ではPlaygroundを表示しないという条件です。
• button.toggle(...): 「Play」ボタンがクリックされるたびに、2つの関数を交互に実行します。
  • 最初の関数は、ボタンにactiveクラスを追加し、Playgroundのdivを表示します。また、setupフラグを使って、playground関数（Go Playgroundのコアロジック）が一度だけ初期化されるようにします。playground関数には、コード入力エリア、出力エリア、実行/フォーマット/共有ボタンのjQueryオブジェクトが渡されます。
  • 2番目の関数は、ボタンからactiveクラスを削除し、Playgroundのdivを非表示にします。
• button.show(): 初期状態で非表示になっているボタンを表示します。
• $('#menu').css('min-width', '+=60'): ナビゲーションメニューの最小幅を60px増やし、新しい「Play」ボタンが追加されてもレイアウトが崩れないようにします。

doc/style.css のドロップダウンPlayground関連スタイル

/* drop-down playground */
#playgroundButton,
div#playground {
	/* start hidden; revealed by javascript */
	display: none;
}
div#playground {
	position: absolute;
	top: 63px;
	right: 20px;
	padding: 0 10px 10px 10px;
	z-index: 1;
	text-align: left;
	background: #E0EBF5;

	border: 1px solid #B0BBC5;
	border-top: none;

	-webkit-border-bottom-left-radius: 5px;
	-webkit-border-bottom-right-radius: 5px;
	-moz-border-radius-bottomleft: 5px;
	-moz-border-radius-bottomright: 5px;
	border-bottom-left-radius: 5px;
	border-bottom-right-radius: 5px;
}
div#playground .code {
	width: 520px;
	height: 200px;
}
div#playground .output {
	height: 100px;
}

これらのCSSルールは、ドロップダウンPlaygroundの見た目と配置を定義します。

• display: none;: JavaScriptによって表示が制御されるため、初期状態では非表示にします。
• position: absolute; top: 63px; right: 20px;: Playgroundをナビゲーションバーの右下（トップバーの高さ63pxの下）に絶対位置で配置します。
• z-index: 1;: 他のコンテンツの上に表示されるようにします。
• background, border, border-radius: ドロップダウンの背景色、ボーダー、角丸を設定し、視覚的なデザインを整えます。
• .codeと.outputのwidthとheight: コード入力エリアと出力エリアのサイズを固定します。

lib/godoc/godoc.html のHTML構造

{{if .Playground}}
<script type="text/javascript" src="/doc/play/playground.js"></script>
{{end}}

...

<div id="topbar"{{if .Title}} class="wide"{{end}}><div class="container">
...
<div id="menu">
...
{{if .Playground}}
<a id="playgroundButton" href="http://play.golang.org/" title="Show Go Playground">Play</a>
{{end}}
...
</div>
...
</div></div>

{{if .Playground}}
<div id="playground" class="play">
	<div class="input"><textarea class="code">package main

import "fmt"

func main() {
	fmt.Println("Hello, 世界")
}</textarea></div>
	<div class="output"></div>
	<div class="buttons">
		<a class="run" title="Run this code [shift-enter]">Run</a>
		<a class="fmt" title="Format this code">Format</a>
		<a class="share" title="Share this code">Share</a>
	</div>
</div>
{{end}}

このHTMLスニペットは、Goテンプレートの条件分岐（{{if .Playground}}）を使って、Playground関連の要素がレンダリングされるかどうかを制御しています。

• playground.jsの読み込み: Playgroundが有効な場合にのみ、Go Playgroundのコアスクリプトが読み込まれます。
• 「Play」ボタン: ナビゲーションバーにid="playgroundButton"を持つリンクが追加されます。
• ドロップダウンPlaygroundのコンテナ: id="playground"を持つdiv要素が、コード入力用のtextareaと出力表示用のdiv、そして操作ボタン（Run, Format, Share）を含んで定義されています。初期のコードスニペットもここに埋め込まれています。

これらの変更が連携することで、godocのウェブインターフェースに、ナビゲーションバーから手軽にアクセスできるインタラクティブなGo Playgroundが統合されています。

関連リンク

• Go言語公式サイト
• Go Playground
• godocコマンドのドキュメント

参考にした情報源リンク

• コミット情報: /home/orange/Project/comemo/commit_data/14108.txt
• GitHub上のコミットページ: https://github.com/golang/go/commit/84386416294922b948e91ebc3226271c1d049998
• Go Playgroundの仕組みに関する一般的な知識
• HTML, CSS, JavaScript, jQueryに関する一般的な知識
• Go言語のテンプレートエンジンに関する一般的な知識