Your SlideShare is downloading. ×
SphinxをMarkdownで使い隊
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

SphinxをMarkdownで使い隊

7,152

Published on

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


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


Published in: Technology
0 Comments
34 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
7,152
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
30
Comments
0
Likes
34
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

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

×