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
   

   View Slide

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
   をはじめよう」
   の著者の一人
   

   View Slide

3. 2015/11/25 Sphinx
   でMarkdown
   を使う(
   仮)
   https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 3/12
   Markdown
   今やMarkdown
   全盛...
   reStructuredText
   は流行らない...
   圧倒的敗北...
   Sphinx
   はreST
   しか使えないから、
   使えない...
   そんなことを考えていた時期が俺にもありました。
   

   View Slide

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
   が使えるようになった
   

   View Slide

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
   

   View Slide

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
   '
   ,
   }
   

   View Slide

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
   で記述 ということも可能
   

   View Slide

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
   先生に感謝
   

   View Slide

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)
   

   View Slide

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
    自体で拡張の議論はあるようす
    議論紛糾で動きがなさそう
    

    View Slide

11. 2015/11/25 Sphinx
    でMarkdown
    を使う(
    仮)
    https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 11/12
    まとめ / Conclusion
    Sphinx
    でもmarkdown
    を使えます
    出力はSphinx
    と変わりない
    ただし、CommonMark
    仕様のみ
    

    View Slide

12. 2015/11/25 Sphinx
    でMarkdown
    を使う(
    仮)
    https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 12/12
    

    View Slide