edownによる整形されたErlangドキュメントの生成

前回に続いてErlangのドキュメントについてです。
前回の内容で、EDocドキュメントを生成する所まではできました。

今回はこれをマークダウン記法で出力して、更にgithub上で機能するリンクまで生成してくれるedownについてのメモです。これもVoluntasさんより教えて頂きました。

マークダウン記法とはWiki記法の一種で、githubの場合は拡張子".md"としておくと、このファイルをマークダウン記法のファイルと認識して適切なHTMLを生成、表示してくれます。

ドキュメントのもととなるソースコード中へのコメント記述は前回のEDocの時と同じです。

導入はrebarを使っている場合はrebar.configに以下のようにedownを追加します。この場合は既にsqlite3を使っており、そこにedownを追加したので結果的にsqlite3とedownの２つを書いてあります。

{deps, [
        {sqlite3, 
         "1.*",
         {git, "git://github.com/alexeyr/erlang-sqlite3.git", 
          {branch, "master"}}},

        {edown, 
         "0.2.*",
         {git, "git://github.com/esl/edown.git", 
          {branch, "master"}}}
       ]}.

この状態で

$ ./rebar  get-deps compile

とするか、またはMakefileが前回の記事のようになっているならば

$ make

とすれば、自動的にedownのソースをダウンロードしてビルドしてくれます。

続いてダウンロードされたedownのルートにある"make_doc"をアプリケーションのトップディレクトリにコピーしてきます。この辺は私の我流ですので違うやり方もあるかと思います。

$ cp deps/edown/make_doc ./

コピーしてきたmake_docをviやemacsなどのテキストエディタ編集します。

$ emacs make_doc

変更するのはパスの設定、github上のアプリケーションルートへのリンクですが、私は更にtop_level_readmeも修正しました。なぜなら既にトップレベルにはrdoc形式のドキュメントがあったためです。将来的にはこっちに切り替えてrdocを無くしても良いのですが、とりあえず今回はdoc以下に作る事にしました。

以下が編集後のmake_docです。

#!/usr/bin/env escript
%% -*- erlang -*-

%% edown is designed to work well with rebar, but in order to use edown
%% to document itself, we need to explicitly set the path to ebin/, so
%% that we pick up the newly built edown doclet. I haven't found a way
%% to do this with 'rebar doc'.
%%
main([]) ->
    code:add_patha("deps/edown/ebin"),
    R = edoc:application(edown, ".",
			 [{doclet, edown_doclet},
			  {src_path, ["src"]},
			  {app_default,"http://www.erlang.org/doc/man"},
			  {top_level_readme,
			   {"./doc/README.md",
			    "http://github.com/hiroeorz/message_box"}}]),
    case R of
	ok ->
	    halt();
	Err ->
	    io:fwrite("~p~n", [Err]),
	    halt(1)
    end.

あとは

$ make_doc

とすればdocディレクトリ以下にmdという拡張子のファイルが作られます。

ただ、この記事へVoluntusさんから頂いたコメントのとおり、rebar.configのedoc_optsに{doclet, edown_doclet}を追加すれば "rebar doc"で、さらにこれをMakefileに書いておけば"make edoc"でマークダウン形式のドキュメントを生成出来るようになります。

以下はこの時点での私のMakefileです。

%% -*- mode: erlang;erlang-indent-level: 4;indent-tabs-mode: nil -*-
%% ex: ts=4 sw=4 ft=erlang et

{erl_opts, [fail_on_warning,                                                    
            warn_export_all]}.
{xref_checks, [undefined_function_calls]}.
{cover_enabled, true}.
{clean_files, ["ebin/*", ".eunit/*"]}.

{edoc_opts, [{doclet, edown_doclet}, %%今回追加 
             {dialyzer_specs, all}, 
             {report_missing_type, true},
             {report_type_mismatch, true}, 
             {pretty_print, erl_pp},
             {preprocess, true}]}.

{deps_dir, ["deps"]}.
{deps, [
        {sqlite3, 
         "1.*",
         {git, "git://github.com/alexeyr/erlang-sqlite3.git", 
          {branch, "master"}}},

        {edown, 
         "0.2.*",
         {git, "git://github.com/esl/edown.git", 
          {branch, "master"}}}
       ]}.

Makefileにこのコマンドを実行するようにするとより簡単です。

ERLC=erlc
ERL=erl
ERLCFLAGS=-o
SRCDIR=src
LOGDIR=./log
BEAMDIR=./ebin ./deps/sqlite3/ebin
DBDIR=./db
APP_NAME=message_box
HOST_NAME=127.0.0.1
REBAR=./rebar
EDOWN=./make_doc

all: clean compile xref

compile:
	@$(REBAR) get-deps compile

xref:
	@$(REBAR) xref

clean: 
	@ $(REBAR) clean

check:
	@rm -rf .eunit
	@mkdir -p .eunit
	@$(REBAR) skip_deps=true eunit 

edoc:
	@$(REBAR) doc

cleardata:
	@ rm -rf $(DBDIR)

boot:
	@ $(ERL) -pa $(BEAMDIR) -name $(APP_NAME)@$(HOST_NAME) -s $(APP_NAME) start

~~edocのところにかいても良かったのですが、とりあえず両方できるようにしてますw こういう所はわりと慎重(笑)~~

あとは

$ make edoc

で、docディレクトリ以下にドキュメントが作られます。

そしてできたファイルを全て git add して pushした上でブラウザでgithub上を見てみれば、綺麗なドキュメントを見る事ができるでしょう。

$ git add doc/*.md
$ git commit -m "add edown documentations."
$ git push origin master

ちなみに私のはこんな感じ。

githubへのリンクはこちら