Sphinx with Markdown

SphinxCon2015 presentation slide.

Transcript

1. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 1/12 Sphinx でMarkdown を使う( 仮) @r_rudi
2. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 2/12 お前だれよ？ / Who are you? @r_rudi / 若山史郎( わかやましろう) / 所属: ツキノワ株式会社 Ansible / 「 入門Ansible」 の著者 Golang / Github Award 日本7 位 Sphinx / 「Sphinx をはじめよう」 の著者の一人
3. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 3/12 Markdown 今やMarkdown 全盛... reStructuredText は流行らない... 圧倒的敗北... Sphinx はreST しか使えないから、 使えない... そんなことを考えていた時期が俺にもありました。
4. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 4/12 Sphinx からMarkdown を使う / Use Markdown from Sphinx source_parsers という機能が入った(1.3 から) parser をsource の種類ごとに変更できるようになった。 recommonmark というdocutils とCommonMark をブリッジするツー ルができた CommonMark: Markdown の標準化( を目指している) 仕様 この二つが揃ったことにより、Markdown が使えるようになった
5. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 5/12 pip でインストー ル / Install via pip 必要なソフトをインストー ル p i p i n s t a l l S p h i n x c o m m o n m a r k r e c o m m o n m a r k
6. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 6/12 conf.py conf.py の以下の行 s o u r c e _ s u f f i x = ' . r s t ' を以下のように変更するだけ s o u r c e _ s u f f i x = [ ' . r s t ' , ' . m d ' ] s o u r c e _ p a r s e r s = { ' . m d ' : ' r e c o m m o n m a r k . p a r s e r . C o m m o n M a r k P a r s e r ' , }
7. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 7/12 使い方 / How to use markdown をrst と同じようにtoctree に組み込むだけ . . t o c t r e e : : : m a x d e p t h : 2 m a r k d o w n F i l e r e s t F i l e ファイル単位で 混合 もOK 通常はMarkdown で記述し、 複雑な表現が必要ならばreST で記述 ということも可能
8. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 8/12 出力 / Output recommomark は CommonMark をdocutils の中間形式に変換している 通常のSphinx と全くおなじ html, epub, latexpdfja このスライドもmd https://github.com/tell-k/sphinxjp.themes.gopher (https://github.com/tell-k/sphinxjp.themes.gopher) を使 用。tell-k 先生に感謝
9. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 9/12 出力例 / Sample JavaScript-Plugin-Architecture @azu_re さん https://github.com/azu/JavaScript-Plugin-Architecture (https://github.com/azu/JavaScript-Plugin-Architecture) 出力例 (https://dl.dropboxusercontent.com/u/218108/JavaScript-Plugin-Architecture.pdf)
10. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 10/12 問題点 / Problem CommonMark 仕様のみ : + 1 : とかない テー ブルがない sphinx のrole やdirective は使えない 拡張もできない CommonMark 自体で拡張の議論はあるようす 議論紛糾で動きがなさそう
11. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 11/12 まとめ / Conclusion Sphinx でもmarkdown を使えます 出力はSphinx と変わりない ただし、CommonMark 仕様のみ
12. 2015/11/25 Sphinx でMarkdown を使う( 仮) https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 12/12