BT

最新技術を追い求めるデベロッパのための情報コミュニティ

寄稿

Topics

地域を選ぶ

InfoQ ホームページ ニュース Try .NETによるインタラクティブな.NETドキュメントの作成

Try .NETによるインタラクティブな.NETドキュメントの作成

原文(投稿日:2019/06/29)へのリンク

Microsoftは先頃、.NET Core用の対話型ドキュメントジェネレータであるTry .NETをオープンソース化した

Try .NETは、C#のインタラクティブなドキュメントを作成可能な、.NET Core Global Toolである。さまざまなプログラミング言語用の同種ツール(Jupyterなど)と同じように、説明テキストと実行可能なライブコードの両方を含んだドキュメントを生成する。

同社シニアプログラムマネージャのMaria Naggaga氏は、開発の背景となった動機について、次のように説明している。

さまざまな言語において、開発者のエコシステムは、ドキュメントの参照、コードの編集、実行をすべてひとつの場所で行えるような、インタラクティブなドキュメントをコミュニティに提供しています。[...] 私たちにとって最も重要なのは、オンラインとオフラインの両方で、インタラクティブなドキュメントを提供することでした。オフラインのエクスペリエンスにおいては、コンテンツライタの現在のワークフローにプラグイン可能なエクスペリエンスを開発する必要がありました。

ドキュメントはすべて、一連のインストラクションとコードスニペットを含んだマークダウンファイルで構成されている。さらにTry .NETでは、コードブロックに拡張マークダウン表記法を使用して、ソースコードファイル内の特定領域を参照できるようにしている。この方法であれば、コードブロック内にコードサンプルを書き下す必要はなく、別のコードファイル内に定義されたC#の領域を参照するだけでよい。

拡張マークダウン表記法を使用することで、通常は次のように記述するC#コードブロックを、

```cs 
Console.WriteLine("Hello World!");
```

次のように簡単に記述することができる。

```cs --region helloworld --source-file ./Snippets/Program.cs 
```

--regionは、Program.csというファイル内にある、helloworldという名のC#コードの#regionを参照する。コードブロックの拡張マークダウン表記の詳細とその使用例は、ツールのGitHubリポジトリで紹介されている。

このツールのもうひとつの興味深い機能は、.NET Coreテンプレートと組み合わせて使用できることだ。現在Try .NETで使用可能な公開テンプレートは、マークダウン拡張表記法を示すために作成されたひとつのみだが、.NET Coreの既存機能を使えば、カスタムテンプレートをローカルに作成することができる。

MicrosoftのパートナープログラムマネージャであるScott Hanselman氏も、氏の個人的なブログで、インタラクティブなワークショップやオンラインブックの作成など、さまざまな目的にTry .NETを使用できる、と述べている。

Visual Studioをインストールせずに.NETを教えてくれる優しい入り口であるだけでなく、独自のMarkdownをライトアップするツールキットでもあるのです。

Try .NETの背景となった開発活動は、2年前、docs.microsoft.comのインタラクティブ機能をリリースしたことから始まった。インタラクティブな.NETドキュメントは、IntelliSense(コード補完用)などのIDE的な機能も備えており、さらに豊かなユーザエクスペリエンスを提供する。Try .NETによって生成されたオンラインドキュメントの例は、ここここに公開されている。

この記事に星をつける

おすすめ度
スタイル

BT