SphinxCon JP を開催しました

つい先日、SphinxCon JP 2014 が開催されました。
僕は所用があったため、午後の発表と懇親会だけ参加しました。
「Sphinx をはじめよう」というテーマの通り Sphinx 初心者/中級者に向けた発表がメインでしたが、
本家のアップデート報告、事例紹介、拡張、テーマ、おとなりさん紹介と幅広い内容で
(スタッフなのに)いち参加者として楽しませていただきました。

Sphinx 拡張についてまとめました

また、発表者のひとりとして Sphinx 拡張について整理しました。
スライドはこちらです。

まとめた成果についてはこちらで公開しています。
Survey of Sphinx extensions

Sphinx 拡張の整理については、以前からやろうとは思っていたものの
手間を考えるとなかなか踏みだせないテーマだったのでいい機会ではありました。

r_rudi さんの Sphinx 拡張 探訪 2012 の時点では
Sphinx 拡張は 100個以上あるとあったので、ある程度覚悟はしていたのですが、
実際にリストアップすると 230個も拡張が出てきました。
2年の間に随分増えたものです。おかげで骨が折れました…。


実はもう一本、話したいテーマとして markdown と reST を比較して
拡張性と多様性、方言について思うところを話してみたかったのですが、
他のセッションとややネタがかぶってしまっていたのと、
カンファレンスのテーマ(Sphinx をはじめよう)とも少しズレが有るよね、ということで
今回は不採用となっていました。
これはどこかの機会にまとめられるといいなとは思ってます。

これからのドキュメント(ツール)の話をしよう

懇親会で何人かの方と相談しながら、ドキュメント全般について話す場の相談をしていました。

現在、ドキュメント関連のコミュニティはいくつかありますが、個人的な印象ではそれぞれがバラバラに活動しているような気がしています。

例えば Sphinx と Re:VIEW では別のコミュニティとして動いていますし、
翻訳をしている人たちもプロジェクトごとに集まっていることが多いように思います。
マークアップ言語やツール、プログラミング言語や活動内容(出版、翻訳、リファレンスなど)など
それぞれのテーマごとに幾つものグループに分かれてしまっているため、
知識や問題などがお互いにシェアされず、似たような落とし穴にはまったり、
車輪の再発明が繰り返されているような節があります。

翻訳ひとつ取っても、Jekyllrb-ja プロジェクトと Rails Guides プロジェクト、
そして Sphinx プロジェクトでは翻訳に使っているツールがそれぞれ異なっています。
向き不向きもあるので一概には言えませんが、こうした部分でナレッジやツールが共有されると
やりたいことにもっと注力できるようになるかもしれません。

こうしたテーマを話す場として、なんらかのイベントをやろうと画策しています。
まずは 版管理+自動組版 で版や組版について
議論や相互理解が深まると良いなあと考えています。
そして、できればテーマを変えて第二弾、第三弾と広げられると良いなあと思っています。

まとめ

これからもがんばりましょう。

Sphinx-1.3 に numfig っぽい機能を付けた話

このブログでは numfig の闇と向き合う の記事から numfig との取っ組み合いをしていましたが、
ひょんなことから Sphinx 本体の改修を手伝うことになり、
つい先日 Assign numbers to figures, tables and code-blocks というプルリクが本体に取り込まれました。
また、別のプルリクとして Add :numref: role to refer figures, tables and code-blocks by its fignum が送られていて、
ふたつを合わせると numfig の図表番号という考え方が Sphinx 本体にマージされることになります。

Sphinx 拡張を書くのと比べると Sphinx 本体をいじるのはできることが多くなるかわりに、
奔放なコードを書くと禍根を残すことになるので三倍ぐらい丁寧にコードを読むことになりました。


また、他にも code-block にキャプションを振る機能や graphviz 拡張のキャプションまわりの改善など、
toctree や参照まわりに関する改善を積み重ねてきました。
詳しい日付はまだ出ていませんが、Sphinx 1.3のβ版は近日リリースされるとのことです。

論文や書籍を書くなど、numfig に興味を持っているひとは Sphinx 1.3β にチャレンジしてみてください。
conf.py に numfig = True と書くだけで図表番号が採番されるようになります。


リリースを目前にして、マージされたプルリクのリストを見て、頑張ったなあという感慨を抱いたので記録代わりに記事を書いておきます。

visio2img と sphinxcontrib-visio のメンテナーになりました

少し前、インターン生として @yassu がうちの会社に来ていたので、
その際にドキュメント作成に使うツールを作ってもらいました。

visio2img と sphinxcontrib-visio の 2パッケージです。
それぞれ、visio2img は Visio ファイルから画像ファイルを抽出するコマンドラインツール、
sphinxcontrib-visio は Sphinx 文書の中に Visio 画像を埋め込む Sphinx 拡張です。

ネットワークエンジニアを筆頭に Visio を使って画像を作っている方は多いと思いますので、
これらのツールを使ってよりより便利にドキュメントをつくって貰えればと思います。

なお、visio2img は内部で Visio コンポーネントを呼び出しているため、
実行環境には Visio がインストールされている必要があります。

visio2img は Microsoft さんの提供でメンテナンスされています

これらのパッケージのメンテナンスには Visio のライセンスが必要となるため、
ライセンスを持っている僕がパッケージのメンテナとして活動しています。

さて、この僕の持つ Visio のライセンスですが、実は Microsoft さんによって提供されています。
去年の 5月に開催されたカンファレンスカンファレンスで Microsoft さんから頂いたものを使っています。
おかげさまで visio2img のメンテナンスに役立てることができました。

改めて Microsoft さんには感謝したいと思います。

今後の予定

とりあえず、自分が思いつく一通りの機能は実装して一段落したところです。
使っていただいて、気になる点があればレポートをお願いします。

SphinxCon JP を開催することにしました

すでに渋谷では SphinxCon 開催の話題でもちきり状態で、
ご存じない方はもういらっしゃらないとは思いますが、今年も SphinxCon JP 2014 を開催します。

ノリと勢いで 2012, 2013 とやってきていましたが、なんと 3年目を迎えることになりました。
参加者も発表者も募集しているので、興味がある方はお誘い合わせの上登録をお願いします。
今年の状況によっては、2015 の開催につながるかもしれないので、ちょっとでも興味があれば飛び込んでみてください*1。


さて、この SphinxCon JP の開催までは精鋭スタッフの努力によって成り立っています。
今年はそのリーダーとして @usaturn 氏が先頭に立ち、来るイベント当日に向けて準備を進めています。
そこで、今回はリーダー @usaturn 氏のために、新たに Sphinx 拡張を作ってみました*2。
それが sphinxjp.usaturn です。

sphinxjp.usaturn は warning や note などの、admonition と呼ばれるテキストブロックの記述に用います。
sphinxjp.usaturn の設定を行うと usaturn ディレティブが追加され、
reST の中でうさたーんに注意書きをしゃべってもらうことができます。
たとえば

.. usaturn:: こんにちは、私はうさたーんです。

とマークアップを行うと、次のように変換されます。
f:id:tk0miya:20140907111027p:plain

また、sphinxjp.usaturn は add_character_admonition という API を提供しているため、
conf.py で設定を書き加えることでうさたーん以外にも喋らせることができます。

この機能を用いると、キャラクターの対話形式の記事も簡単に作ることができます。

.. usaturn:: こんにちは、私はうさたーんです。

.. shimizukawa:: こんにちは、私はペンです。
   :align: right

.. usaturn:: いいえ、それはペンではありません。久美です。

.. shimizukawa:: ケン、座ってください。
   :align: right

.. usaturn:: 私も寿司が好きです。

f:id:tk0miya:20140907111545p:plain

とっても便利ですね。

まとめ

  • SphinxCon JP 2014 が開催されます。スピーカーも参加者も大募集中です。
  • sphinxjp.usaturn というモジュールを作りました
  • 犯人はこいつです

*1:Sphinx だけではテーマが限られてしまうので、どうせなら次は他のドキュメンテーションツールを混ぜつつ、DocTool Conf みたいに昇華できるといいのではないかとか、妄想はいろいろありますね。他のツールの状況とかも聞いてみたいし！

*2:sphinx-users.jp 界隈では敬意や感謝を表すために Sphinx 拡張を贈り合う習慣があるとかないとか... 参考: sphinxjp.shibukawa, sphinxjp-tk0miya

YAPC::Asia 2014 に行ってきた #yapcasia

相変わらず perl を書いてはいないのだけど、あのお祭り感が大好きなので
今年も YAPC::Asia に行ってきました。

帰り際に HUB で飲んでた時にスポンサーの人に煽られたのでなるはやで書いてます。


いつもは話半分、コード書き半分ぐらいの感じで過ごすのですが、
今回はわりかしまじめに(?)話を聞いて回ってました。

特に興味深かったのがこの辺り。

誰かが楽しそうに発表したり、面白いことをやってたりすると、すごく刺激されますね。
なにか人に話せる面白いことやりたいですね。

ちょうど JSON Schema を触るのを放置していたので、このあたりのことをやれという天啓だったのかもしれません。
ツッコミも飛んできたのでぼちぼち再開しようと思います。


毎回のことながら、YAPC はやる気を充電してくれるすごいイベントですね。
次回にはなにかネタを持っていけるよう精進していこうと思います。


最後に、今回の YAPC で聞いた中で、声に出して読みたいいい言葉をメモっておきます。



only ディレクティブの微妙なうごき

only ディレクティブを組み合わせるとあれこれ微妙な挙動が発生するようです。

最初は toctree と only ディレクティブの組み合わせについて悩んでいたのですが、
他にも only ディレクティブに関わる動きを @shimizukawa に教えてもらったので
合わせて紹介します。


toctree が 2重登録される

only ディレクティブの下に toctree ディレクティブを配置すると、
その toctree が 2重登録されてしまいます。

例えば、次のような reST を書いてみます。

.. index.rst

heading
========

.. toctree::

   sub

.. sub.rst
続きを読む

astah の画像を Sphinx に埋め込む拡張を作ってみた: sphinxcontrib-astah

先々週に cacoo の拡張をつくってそのあとパッケージングもしたのですが、
それに味をしめて(?) UML 系のツールとして名高い astah 向けの拡張もつくってみました。
sphinxcontrib-astah です。

やっていることは超シンプルで、内部で astah-command.sh を呼び出して いるだけです。


この間 cacoo 向けの拡張をつくった時に気づいたのですが、
API やコマンド経由で画像を生成するツールで、
なおかつ画像のフォーマットが常に PNG や JPEG などのラスター形式のものについては、
sphinxcontrib-cacoo の実装がほぼそのまま使えるのではないかと思います。

astah 拡張を作るときは cacoo の API を呼び出している部分を
astah-command.sh の呼び出しに置き換えるぐらいの作業で対応することができました。

cacoo 拡張では次のことをしています。

  1. image ディレクティブを拡張して cacoo-image ディレクティブを作成 (オプションも継承)
  2. cacoo-image ディレクティブでは image ノードを cacoo_image ノードに置き換える (このとき、image ノードのオプションは引き継ぐ)
  3. doctree-resolved イベントで cacoo_image ノードから画像を生成し、image ノードに置き換える

こうすることで、出力形式ごとの(HTML, LaTeX 用などの) visitor 関数を書く必要がなくなるため、
image ディレクティブ(や figure ディレクティブ)の豊富なオプションをサポートしつつ、
なおかつツールが生成した画像を読み込むことができるようになります。


もしドキュメントの出力に合わせて画像の形式を変更したいなどの要望が出てくると、
実装はもう少し面倒なことになりそうな気がします。
blockdiag や graphviz などでは、画像フォーマットを切り替えたり、
ベクタ形式の画像を生成したりと割と細かいことをしているのでこういった方法は使えないのですが、
新しいツールをサポートするときにお手軽に拡張を作るときは便利かもしれません。



こうしたサードパーティのツールを使う場合、テストを書くのが面倒なのが玉に瑕ですね。
mock を介したりしつつテストを書くと良いのでしょうが、
このふたつの拡張に関してはテストコードがない状態です。

テストがないコードに嫌悪感のある方、すっきりするチャンスです。
当方プルリクをお待ちしております:-)