Erlang と私と Sphinx- Happy Life with Erlang and Sphinx-

Tokyo Erlang Workshop #52010/08/27渋川よしき

自己紹介：渋川よしき• 仕事

– 大手製造業の社内 SE– 社外で技術習得して社内で楽をする

• 参加コミュニティ– SphinxUsers.jp

• 翻訳ハッカソンとかを継続開催予定– 日本 XP ユーザグループ代表

• 9/4 に XP 祭り 2010 を早稲田で開催– とちぎ Ruby– Python 温泉 ( 系 )

• 11/14 に Python Hack-a-thon

• 今年出した本– IT 業界を楽しく生き抜くための

つまみぐい勉強法 ( 技術評論社 )– エキスパート Python プログラミング ( アスキーメ

ディアワークス )

Twitter: @shibukawa

Erlang と私と Sphinx

2009 年 2010 年

Erlang勉強した

い

Erlang と私と Sphinx

2009 年 2010 年

初 Erlang(fizz-buzz)

川崎 code-camp で初 Erlang

Erlang と私と Sphinx

2009 年 2010 年

実践 EUnit を翻訳http://articles.shibu.jp/category/776137-1.html

Erlang と私と Sphinx

2009 年 2010 年

EUnit のリファレンスを翻訳http://articles.shibu.jp/category/777978-1.html

Erlang と私と Sphinx

2009 年 2010 年

Erlang Efficiency Guide を翻訳http://erlang.shibu.jp/efficiency_guide/

Erlang と私と Sphinx

2009 年 2010 年

この翻訳で初めて Sphinx を導入

Erlang と私と Sphinx

2009 年 2010 年

Sphinx の 0.6 系の翻訳http://sphinx.shibu.jp/

Erlang と私と Sphinx

2009 年 2010 年

OSC 2009 Tokyo/Fall で LThttp://blog.shibu.jp/article/33377933.html

Erlang と私と Sphinx

2009 年 2010 年

本の原稿も Sphinx

Erlang と私と Sphinx

2009 年 2010 年

SphinxUsers.jp 設立・会長就任

Erlang と私と Sphinx

2009 年 2010 年

翻訳本も Sphinx

Erlang と私と Sphinx

2009 年 2010 年

Sphinx 1.0 翻訳

Sphinx と Wiki の比較

プレーンテキストによる簡易マークアップ

レンダリング　→静的 HTML 生成　→ PDF/LaTeX などエディタでオフライン編集　→バージョン管理なしキーワードに対してリンクツリー構造

プレーンテキストによる簡易マークアップ

レンダリング　→ HTML　→ Web アプリケーションブラウザでオンライン編集　→バージョン管理内蔵ページに対してリンクセミラティス構造

□Sphinx □Wiki

Sphinx と Wiki の構造の違い

WikitoRuby

Ruby

Hiki

RWiki

るびま

toRuby

たのしい Ruby

dRuby による・・・

とちぎ Ruby 会議

02

01レポート

def 書籍情報

参考図書

Sphinx と Wiki の感想の比較

ツリーによるナビ　→ロジカルツリー　→トップダウン構造水平に広げやすい構造がぶれないスモールリファクタリング

しやすい

Web サーフィン感覚　→ Wikipedia で時間を消

耗　→迷子ページも　→全体像つかみにくい深めやすい構造は自由構造修正は大工事・・・

□Sphinx □Wiki

Python のドキュメンテーションには手書きと自動作成と２種類あった。両方とも開発者、ユーザともにメリット、デメリットがある。手書きの方が品質は高いが、メンテナンスは苦痛である

Werkzeug 0.2 ではこの２つの組み合わせに挑戦した。 Docutils をベースにコードからの自動抽出を追加し、完全にコードとドキュメントの同期が取れるようになった。 Georg Brandl はこのツールを書き直し、 Sphinxとしてリリースした。これは Python 2.6, 3.0 のドキュメントでも使用され、Python 以外のプロジェクトもサポートしている

これは今までで最高のドキュメントツールだ。自動相互リンク、索引の作成もサポートしている。拡張 API を使えばさらなる自動化も期待できる

Twitter の写真を引用しました

それ以外にも・・・

• BPStudy #30 で Sphinx の紹介• Python Hack-a-thon で Sphinx ハンズ

オン開催• 電子書籍の動向調査の原稿依頼がキタ• 産業技術大学院大学で発表

それ以外にも・・・

• BPStudy #30 で Sphinx の紹介• Python Hack-a-thon で Sphinx ハンズ

オン開催• 電子書籍の動向調査の原稿依頼がキタ• 産業技術大学院大学で発表

Erlang を勉強するつもりが、気づいたら Sphinx エヴァンジェリス

トに！

でも、ちょっと待って！

Sphinx 1.0 から新機能• Python 、 C 以外のドキュメントも書ける

ように• 自分で対応言語を増やせる .. rb:module:: berrymq

.. rb:function:: talk( 識別子 )

メッセージを送ります

クライアントとコネクションを張ったら :rb:func:`talk` が使えるようになります

berrymq.talk(識別子 ) メッセージを送ります

クライアントとコネクションを張ったら talk() が使えるようになります

Ruby のソース ビルド結果

ということで・・・

Erlang ドメインを実装

今のところの対応• Erlang 専用の 4 つのディレクティブとロー

ルを追加

– モジュール– 関数– マクロ– レコード

モジュールディレクティブ

.. erl:module:: lists

• モジュール名を引数に取る• モジュール索引に項目が追加され、ページジャン

プできる• これを設置した後の関数は、これの中にあるとみ

なされる。

関数ディレクティブ

.. erl:function:: append(ListOfLists) -> ok

:param ListOfLists: くっつけたいリストのリスト

ここに箇条書きでもなんでも自由に文章書けます。

• 関数名を引数に取る• メソッドの省略、返値も記述できる• 引数、返値の説明は :param:, :type:, :return:, :rtype:

フィールドを使う

マクロ、レコードディレクティブ

.. erl:macro:: NOTEST

テストの実行をやめる

.. erl:record:: #person

人の情報

• マクロ名、レコード名• ディレクティブ内に自由に文章が書ける• レコードの要素ごとの説明が書けるようには

なってません。作成中です。

モジュールロール

Erlang のテスティングフレームワークには、 2種類あり、簡単な方が :erl:mod:`eunit` です。

• ドキュメントの文章中から、モジュールの定義場所へのリンクを貼る

関数ロール

:erl:func:`sets:from_list/1` と、 :erl:func:`sets:to_list/1` を使えば、重複要素のないリストが簡単に作れます。

• ドキュメントの文章中から、関数の定義場所へのリンクを貼る。

• arity とモジュールを指定する ( 同じモジュール内ならばモジュールは省略可 )

マクロ、レコードロール

:erl:macro:`APRILFOOL` は、エイプリルフールにコンパイルする時にのみ設定されるマクロです。

:erl:func:` これ <lists:reverse/1>` を 2 回実行すると、時間コストはややかかります。

• arity がない以外は関数のロールとほぼ一緒です。• 他のロールもですが、 < > を使うと、ドキュメ

ントに表示されるラベルを変えることもできます。

使い方• easy_install sphinxcontrib-erlangdomain

• Sphinx のプロジェクトを作ったら、 extensionsに’ sphinxcontrib.erlangdomain’ を追加

Sphinx でドキュメント書くといいこと

• 豊富なマークアップを活用して記述できる

• 大規模文章でも書きやすい• Erlang はドキュメントを大事にする文化• iPad に出すとモテる！？

Sphinx についての詳しい情報はSphinxUsers.jp へ

– インストール方法– リファレンスの完全日本語訳– Sphinx を使った日本語サイト一覧– ウェブサイトの作り方– チュートリアル– ePub の出し方– 翻訳のやり方– よい文書の書き方

Sphinx のこれから良くなる点• PDF 出力–お手軽 rst2pdfだと見た目が・・・日本人も参戦！• http://twitter.com/tk0miya さんががんばってます！

– LaTeX経由・・・すみません僕の環境ではまだ成功してません。 pTeXLive 入れればいいの？

• 各国語対応–検索機能だとか。

• GUI– 詳しくない人に広めるなら欲しいよね？

Sphinx で救われる方• 仕事のドキュメントが Excel で疲れた方• 仕事のドキュメントが Word でリファレンス作りに疲れ

た方• 仕事のドキュメントが LaTeX でコンパイルエラーに疲れ

た方• 仕事のドキュメントがヘビー級な CMS で、不要な二酸

化炭素を排出している気がして、気になって眠れない方

Sphinx と Erlang で、Happy Documentation Life!

そういえば Erlang はどうなったの？

Project Euler

日本人で一時、 1位に！現在は 2位です。ヒヨッコですが。