F# Formattingでドキュメントを生成してみる

F#

Tomas Petricekさんが開発されている、F# Formatting を試してみました。
GitHub : https://github.com/tpetricek/FSharp.Formatting
Documents : http://tpetricek.github.com/FSharp.Formatting/index.html


このツールはF# Snippetsでも使われていますので、F#erにはお馴染みですね。
シンタックス・ハイライトのみならず、マウスオーバーでメンバの情報まで表示される優れものです。


またこのツールは、文芸的プログラミング(Literate programming)にも対応しています。
http://tpetricek.github.com/FSharp.Formatting/demo.html
使ってみた感想ですが、とても良い感じです。
OSSの開発にはかなり便利なのではないでしょうか。
みなさんにも使ってみて頂きたいので、簡単なサンプルをご用意しました。

本題

このツールを使ってドキュメントを生成し、GitHub Pagesで公開するところまでを簡単にご紹介したいと思います。
生成されたドキュメント : http://nobuhisa.github.com/DocSample/Script.html
サンプルプロジェクト : https://github.com/Nobuhisa/DocSample


ページを公開するまでの流れですが、
0. 下準備(NuGetでFSharp.Formattingを追加、リポジトリの準備 等)
1. F# でオープンソースなプログラムを書く
2. 使い方などを示す、サンプルスクリプト(.fsx)を用意する
3. サンプルに解説を付け加える*1
4. F# Formattingを使ってドキュメントを生成！
5. GitHub Pages(gh-paegs)を使って、公開してみる
このような感じです。
順に見ていきます。

FSharp.Formatting の準備

Visual Studioをお使いの場合は、NuGetから簡単にインストールできます。
"FSharp.Formatting"で検索してみてください。

インストールが完了すると、packages以下にいくつかのスクリプトファイルも合わせて配置されます。
(このような感じ)
その中のliterate.fsxが核になります。とりあえず準備はここまで。

プログラムを書く

サンプルとして、以下のような素晴らしいプログラムを用意しました。
https://github.com/Nobuhisa/DocSample/blob/master/DocSample/Library1.fs

namespace DocSample

module Sample =
    /// あいさつ関数です。
    let hello () = printfn "hello, world"

    /// サンプルクラスです。
    type Sample() =
        /// サンプルメソッドです。
        member this.Sample () = printfn "F#!F#!"

とても胸が熱くなるサンプルです。

サンプルスクリプトの用意

以下のようなスクリプトファイルを用意したことにしましょう。

#load "Library1.fs"
open DocSample

Sample.hello ()
let s = Sample.Sample()
s.Sample()

使い方を示すような、そんなスクリプトです。

文芸的プログラミング！

誰が文豪になるか？君でしょう！
用意したスクリプトを、以下のように書き換えます。
これはF# Formattingのルールに沿って記述します。
https://github.com/Nobuhisa/DocSample/blob/master/DocSample/Script.fsx

(**
THIS IS A SAMPLE
================
吾輩はサンプルである。名前はまだない。

Sub Title
---------
- sakurai
- suzuki
- _tahara_
- nakagawa

`コミュニティ`

- [F# User Group - Japan](https://github.com/Nobuhisa/FSUG_JP/wiki)

*)

(*** hide ***)
// この部分を隠したい時
#load "Library1.fs"
open DocSample

(**
### Usage:
この素晴らしいサンプルは以下のように使用します。
*)
Sample.hello ()

let s = Sample.Sample()
s.Sample()

(**
おわりに
-------
Good job, Tomas!
*)

内容は適当なので気にしないでください。
追記した部分はコメントになっていますので、スクリプトの実行には影響しません。

ドキュメソトを生成する

packagesに配置されたliterate.fsxを使って生成するのですが、直接使用するのは大変なので、
以下のようなビルドスクリプトを用意してみました。
流用して頂いても構いません。(環境に合わせてパスを変更してください)
サンプルでは、literate.fsxと同じフォルダに配置しています。
build.fsx

#I "../lib/net40"
#load "literate.fsx"
open FSharp.Literate

let processDirectory () =
    let path     = __SOURCE_DIRECTORY__
    let dir      = path + @"..\..\..\..\DocSample"
    let template = path + @"\templates\template-project.html"
    let projectInfo =
        [ "page-description", "My Sample Document"
          "page-author", "Nobuhisa"
          "github-link", "https://github.com/Nobuhisa"
          "project-name", "DocSample" ]

    Literate.ProcessDirectory(dir, template,
        outputDirectory = dir + "\\docs", replacements = projectInfo)

do
    printfn "Start..."
    processDirectory ()
    printfn "finish!"

    #if INTERACTIVE
    #else
    System.Console.ReadKey() |> ignore
    #endif

Visual Studioをお使いの方は、Alt + Enterで実行してみてください。
問題がなければドキュメントが生成されます。
サンプルでは、プロジェクトのフォルダにdocsというフォルダを追加し、そこにファイルを生成します。
生成されていない場合は、プログラムやパスの指定に問題があるか、日頃の行いに問題があるかのどちらかです。


なお、このdocsフォルダには必要なスタイルシート、jsファイルが含まれていませんので、
packages以下にあるcontentというフォルダをコピーしてきてください。
まずはローカル環境でHTMLファイルがきちんと表示できるか確認してみてください。

GitHub Pages にて公開

以下のようになります。
http://nobuhisa.github.com/DocSample/Script.html


GitHub Pagesの公開方法は沢山出回っていますので、詳細は省きます。
リポジトリに"gh-pages"というブランチを作って、そこにファイルを配置するだけです。
(こんな感じ)
配置してから表示可能になるまで、少し時間がかかるようです。焦らず数分待ってみてください。


Tomasさんが用意されている以下のドキュメント、
http://tpetricek.github.com/FSharp.Formatting/demo.html
これも、スクリプト(demo.fsx)から生成されています。

まとめ

疲れた！

*1:F# Formattingのルールに沿って記述します