Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

SphinxをMarkdownで使い隊

14,779 views

Published on

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


Published in: Technology
  • Be the first to comment

SphinxをMarkdownで使い隊

  1. 1. SphinxをMarkdownで使い隊 2013-07-07 @iktakahiro ~ ついでに渡り廊下も走り隊 ~
  2. 2. このスライドに書いてあること Sphinxを、MercurialとPandocを組み合わせて Markdown記法で運用できるようにしたお話。 Mercurialとの連携方法も紹介するよ。
  3. 3. 自己紹介 @iktakahiro 株式会社ALBERT システム開発部 レコメンドエンジンとか作ってるよ! 最近気になっていること: 近頃のIPAはなぜ初音○ク推しなのか
  4. 4. 背景 社内でHRTKさんがSphinx勉強会を開催してくれて、 やっぱ便利よねぇと思ったのでなんとかカジュアルに 使える運用を検討したいと思ったでござる。
  5. 5. Sphinxとは? Python製のドキュメンテーションツール reStructuredTextでマークアップする 拡張でダイアグラムとかも書ける Wikiではない [参考] ドキュメントを作りたくなってしまう魔法のツールSphinx http://www.slideshare.net/shimizukawa/sphinx-6084667
  6. 6. reStructuredTextとは? 軽量マークアップ言語の1つ Sphinxに採用されている Markdownよりも表現力に優れる Markdownほど使われていない [参考] reStructuredText入門 http://sphinx.shibu.jp/rest.html
  7. 7. 何が問題か? Sphinxは楽しいけど、2つの壁がありそう。 reStructuredText覚えるの面倒くさい make html は誰がいつやるの?
  8. 8. ではどうするか? reStructuredText覚えるの面倒くさい => Markdownで書いてみよう make html は誰がいつやるの? => hookスクリプトにやらせてみよう
  9. 9. Markdownで書くために SphinxはreStructuredTextにのみ対応 Pandocを使おう!
  10. 10. Pandocとは? Haskell製ドキュメント変換ツール 軽量マークアップ言語の相互変換 WordやPDFへの変換もできるすぐれもの 当然Markdown -> reStructuredText も対応 [参考] 多様なフォーマットに対応! ドキュメント変換ツールPandocを知ろう http://qiita.com/sky_y/items/80bcd0f353ef5b8980ee
  11. 11. # markdown を reSTに変換 pandoc -f markdown -t rst -o test.rst test.md インストールすればコマンドラインから↑このように 使える。 互換性を見たければ↓で試せる http://johnmacfarlane.net/pandoc/try/
  12. 12. # 見出し1 ## 見出し2 ```python print('test') ``` 見出し1 ======== 見出し2 ------- .. code:: python print('test') Markdown reStructuredText Pandocさんによる変換の例
  13. 13. 運用に乗せたい Markdownで書けそうなことは分かった ドキュメントはレポジトリで管理したい Commit∼Pushしたらmake htmlして欲しい hookを使おう!
  14. 14. ディレクトリ構成 /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
  15. 15. ディレクトリ構成(つづき) /var/hg/sphinx/manual1/build/html => make htmlしたときのhtml出力場所 ※プロジェクト作成時の設定による http://example.com/manual1/build/html/ => ブラウザから確認できるURI例
  16. 16. hookスクリプトの中身 #!/bin/bash repository=$1 BASE_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
  17. 17. source/.hg/hgrc の中身 [hooks] pretxnchangegroup.make /var/hg/sphinx/sphinx_hook.sh manual1 レポジトリ名を引数に与えて実行 外部からPUSHされたら実行するhook (hookが失敗したらロールバック)
  18. 18. 処理の流れ 1. レポジトリにPushすると、hookスクリプトが実行される 2. 拡張子 .md のファイルを探し、pandoc で reSTに変換する 3. make html を実行 [補足] 変換後の reSTファイルはレポジトリ管理されない。 あくまで Markdownのファイルをレポジトリ管理する。 index.rst だけはそのまま使ってくだしあ。。。
  19. 19. Pushするだけでブラウザから最新の ドキュメントを確認できる!
  20. 20. Markdownで書ける!
  21. 21. もっと改善ポイント 差分だけpandocすればおk Jenkinsにビルドさせるのも良いかも スクリプトも適当なのでエラー制御ちゃんとしよう 100%互換性がある訳ではないので要研究。 特に拡張周りは結構地雷がある予感がする。
  22. 22. 今回のオチ
  23. 23. sphinxcontrib_markdown SphinxでMarkdownを利用するための拡張 make htmlのあとで変換しているようだ (暗躍しているのはやはりPandocさん) [参考] Sphinx 文書に markdown フォーマットを利用する http://tk0miya.hatenablog.com/entry/2012/12/19/233642
  24. 24. あ、あたしのほうが疎結合なんだからねっ! (ノ \〃)
  25. 25. おわり。

×