SphinxをMarkdownで使い隊

2013-07-07@iktakahiro

~ ついでに渡り廊下も走り隊 ~

このスライドに書いてあること

Sphinxを、MercurialとPandocを組み合わせてMarkdown記法で運用できるようにしたお話。

Mercurialとの連携方法も紹介するよ。

自己紹介

✓@iktakahiro✓株式会社ALBERT システム開発部✓レコメンドエンジンとか作ってるよ！

最近気になっていること: 近頃のIPAはなぜ初音○ク推しなのか

背景

社内でHRTKさんがSphinx勉強会を開催してくれて、

やっぱ便利よねぇと思ったのでなんとかカジュアルに

使える運用を検討したいと思ったでござる。

Sphinxとは？✓Python製のドキュメンテーションツール✓reStructuredTextでマークアップする✓拡張でダイアグラムとかも書ける✓Wikiではない

[参考]ドキュメントを作りたくなってしまう魔法のツールSphinx http://www.slideshare.net/shimizukawa/sphinx-6084667

reStructuredTextとは？✓軽量マークアップ言語の1つ✓Sphinxに採用されている✓Markdownよりも表現力に優れる✓Markdownほど使われていない

[参考]reStructuredText入門 http://sphinx.shibu.jp/rest.html

何が問題か？Sphinxは楽しいけど、2つの壁がありそう。

reStructuredText覚えるの面倒くさい

make html は誰がいつやるの？

ではどうするか？

reStructuredText覚えるの面倒くさい

=> Markdownで書いてみよう

make html は誰がいつやるの？

=> hookスクリプトにやらせてみよう

Markdownで書くために

✓SphinxはreStructuredTextにのみ対応

Pandocを使おう！

Pandocとは？✓Haskell製ドキュメント変換ツール✓軽量マークアップ言語の相互変換✓WordやPDFへの変換もできるすぐれもの✓当然Markdown -> reStructuredText も対応[参考]多様なフォーマットに対応！ ドキュメント変換ツールPandocを知ろう http://qiita.com/sky_y/items/80bcd0f353ef5b8980ee

# markdown を reSTに変換

pandoc -f markdown -t rst -o test.rst test.md

インストールすればコマンドラインから↑このように使える。

互換性を見たければ↓で試せる http://johnmacfarlane.net/pandoc/try/

# 見出し1

## 見出し2

```pythonprint('test')```

見出し1========

見出し2-------

.. code:: python

print('test')

Markdown reStructuredText

Pandocさんによる変換の例

運用に乗せたい

✓Markdownで書けそうなことは分かった✓ドキュメントはレポジトリで管理したい✓Commit～Pushしたらmake htmlして欲しい

hookを使おう！

ディレクトリ構成/var/hg/sphinx => Webサーバーの doc root にしておく

/var/hg/sphinx/manual1 => Sphinxプロジェクト [manual1] のroot

/var/hg/sphinx/manual1/source => rstファイル置き場。ここをレポジトリにする

/var/hg/sphinx/sphinx_hook.sh

ディレクトリ構成(つづき)/var/hg/sphinx/manual1/build/html => make htmlしたときのhtml出力場所 ※プロジェクト作成時の設定による

http://example.com/manual1/build/html/ => ブラウザから確認できるURI例

hookスクリプトの中身#!/bin/bash

repository=$1BASE_DIR="/var/hg/sphinx"DIR="${BASE_DIR}/${repository}"

# pyvenvにSphinx環境がある場合を想定source /usr/local/sphinx/bin/activate

# 変換処理 (長いけどワンライナーだよ）cd ${DIR}/source && find ./ -name "*.md" | sed -e 's/^.*\///' -e 's/\.md$//' | xargs -i pandoc -f markdown -t rst -o {}.rst {}.md

source/.hg/hgrc の中身

[hooks]pretxnchangegroup.make /var/hg/sphinx/sphinx_hook.sh manual1

レポジトリ名を引数に与えて実行外部からPUSHされたら実行するhook(hookが失敗したらロールバック)

処理の流れ

1. レポジトリにPushすると、hookスクリプトが実行される

2. 拡張子 .md のファイルを探し、pandoc で reSTに変換する

3. make html を実行

[補足]変換後の reSTファイルはレポジトリ管理されない。あくまで Markdownのファイルをレポジトリ管理する。index.rst だけはそのまま使ってくだしあ。。。

Pushするだけでブラウザから最新のドキュメントを確認できる！

Markdownで書ける！

もっと改善ポイント

✓差分だけpandocすればおｋ✓Jenkinsにビルドさせるのも良いかも✓スクリプトも適当なのでエラー制御ちゃんとしよう✓100%互換性がある訳ではないので要研究。 特に拡張周りは結構地雷がある予感がする。

今回のオチ

sphinxcontrib_markdown✓SphinxでMarkdownを利用するための拡張✓make htmlのあとで変換しているようだ (暗躍しているのはやはりPandocさん)

[参考]Sphinx 文書に markdown フォーマットを利用する http://tk0miya.hatenablog.com/entry/2012/12/19/233642

あ、あたしのほうが疎結合なんだからねっ！(ﾉ∀＼〃)

おわり。