Sphinx with Markdown

28da29f13a2f4e6f602b7bfa032a94cc?s=47 shirou
November 25, 2015

Sphinx with Markdown

SphinxCon2015 presentation slide.

28da29f13a2f4e6f602b7bfa032a94cc?s=128

shirou

November 25, 2015
Tweet

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