Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Sphinx with Markdown

shirou
November 25, 2015

Sphinx with Markdown

SphinxCon2015 presentation slide.

shirou

November 25, 2015
Tweet

More Decks by shirou

Other Decks in Technology

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