MarginaliaでClojureソースをドキュメント化

前置き

タイトルのままですが、Marginaliaは、ClojureのソースファイルからHTMLドキュメントを作るツールです。JavadocやDoxygenの親戚みたいなものでしょう。文章とソースを左右に並べた2カラムスタイルのHTMLを生成するのが特徴です。

準備

Leiningenプラグインの登録(profiles.clj)
{
  :user {
    :plugins [[lein-droid "0.2.0"]
              [lein-midje "3.1.1"]
              [lein-marginalia "0.7.1"]     ; <=
              ]
    :android {:sdk-path "c:/misc/adk/"}
  }
}

実験用プロジェクト

プロジェクト作成
D:\etude\clj\lein>lein new app margex
Generating a project called margex based on the 'app' template.
project.clj
(defproject margex "0.1.0-SNAPSHOT"
  :description "Marginalia examples. Try some frequently used markup notations."
  :url "http://gpsoft.dip.jp/"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.5.1"]]

  ;; for LightTable.
  :repl-options {:nrepl-middleware [lighttable.nrepl.handler/lighttable-ops]}

  :main margex.core)

project.cljの最初の2行(プロジェクト名、バージョン、description)がHTMLに埋め込まれます。descriptionを日本語で書くと、HTMLが文字化けする可能性があります。Windowsの場合、project.cljをSJISで書けばOKでしたが、HTML自体はUTF-8です。あんまりケアされてないと思います。

マークアップ

公式サイトにはマークアップ記法のリファレンスが無いようでしたが、例えば、こんなことができます。

  • 見出し(<h2>とか)
  • 箇条書き(<ol>とか)
  • <code>
  • <a>
  • <blockquote>

2つのソースファイルで試してみます。

core.clj
;; 名前空間の説明。
;  各コメントブロックの最初の行は、2つ以上のセミコロンで。
;  名前空間の説明を2行以上書く場合は、コメントブロックと(ns ...)の間に
;  空行(セミコロンだけの行)が必要みたい。
;
(ns margex.core)

;; ## Marg Examples
;
; 2つのシャープ(`##`)から行末までが、`<h2>`になる。3つなら`<h3>`。
;
; バッククオート(\`)で囲むと、`<code>`になる。
;
; いわゆるhtmlエスケープが必要。例えば &lt; なら、&amp;lt; と書く。


;; ### 箇条書き

(defn ordered
  "順序付きの箇条書き。`<ol>`相当。

  1. 空行を置き、
  1. 各行は、数字(何でもOK)、ピリオド、スペースで始め、
  1. 空行で終わる

  と思ったけど、終わらない。docstringが終わるまで`<ol>`が続くみたい。"
  [& args]
  (println (apply str args)))

(defn unordered
  "順序なしの箇条書き。`<ul>`相当。

  - 空行を置き、
  - 各行は、ハイフンとスペースで始め、
  - 空行で終わ…
  
  らない。"
  [& args]
  (when args
    (map odd? args)))

;; ### 落とし穴
;; コメントの直後にコードがあると、
;; そのコードに対するコメントだと解釈され、
;; html上では、コードと同じ段か下側に配置される。
;; 
;; よって、このコメントは、pitfall関数のコメントと見なされる。
;; 
;; これを避けるには、コメントの下に空行(コメントではない空行)を置く。
(defn pitfall
  "これは、pitfall関数のdocstringです。"
  []
  (some (comp first seq) ['() {} [:ok :ng]]))
misc.clj
;; 第二の名前空間。
(ns margex.misc)

(defn misc
  "docstringの中でコードを引用するには、インデントを付ければOKです。例えば、
  
    (misc [2014 1 25])

  といった感じです。ただし、前後に空行が必要です。また、コメントの中では効かないようです。
  
  何なら、直接htmlでマークアップしてもいいみたいですね。こっちはコメントの中でも効きます。
  <pre><code>(misc [2014 1 25])</code></pre>"
  [[year month day]]
  (print (format "%04d-%02d-%02d" year month day)))

;; ## その他
;
; 段落を &gt; で始めると、`<blockquote>`になります。
; >Debugging is twice as hard as writing the code in the first place.
; Therefore, if you write the code as cleverly as possible, you are,
; by definition, not smart enough to debug it.
; 
; リンクを張るには、[こんな感じ](http://gpsoft.dip.jp/hiki/)でOKです。
; 
; #### 使い方
; 
; <pre><code>D:\etude\clj\lein&gt;lein new app margex
; D:\etude\clj\lein&gt;cd margex
; D:\etude\clj\lein\margex&gt;lein marg
; </code></pre>
;
; これで、`docs`フォルダの下にhtmlファイルが作成されます。
; スタイルシートが気に入らない場合は、CSSファイルを指定できます(セミコロン区切りで複数列挙も可能)。
; 
; <pre><code>D:\etude\clj\lein\margex&gt;lein marg --css base.css</code></pre>
;
; `base.css`は`docs`フォルダの下に置いて下さい。

使い方

D:\etude\clj\lein\margex>lein marg
Generating Marginalia documentation for the following source files:
   D:\etude\clj\lein\margex\src\margex\core.clj
   D:\etude\clj\lein\margex\src\margex\misc.clj

これで、docsフォルダの下に uberdoc.html が作成されます。デフォルトではスタイルに日本語フォントが指定されず、セリフ体で表示されます。独自のCSSファイルを指定するには --css オプションを使います。

D:\etude\clj\lein\margex>lein marg --css base.css
base.css
body {
  font-family:'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif,
              'Lucida Grande', 'Hiragino Kaku Gothic ProN',
              'ヒラギノ角ゴ ProN W3', Meiryo, メイリオ, serif
}

CSSファイルも、docsフォルダの下に置きましょう。

できあがりは、こんな感じです(Windows8 & FireFox)。

marginalia

全文はこちらで見ることができます。

Last modified:2014/01/25 01:41:16
Keyword(s):
References:[FP: 関数型プログラミング]
This page is frozen.