(hatena (diary ’Nobuhisa)) このページをアンテナに追加 RSSフィード Twitter

13/03/28 :

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

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"で検索してみてください。

f:id:Nobuhisa:20130328002330p:image

インストールが完了すると、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のルールに沿って記述します

スパム対策のためのダミーです。もし見えても何も入力しないでください
ゲスト


画像認証