Slide 1
Slide 1 text
2015/11/25 Sphinx
でMarkdown
を使う(
仮)
https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 1/12
Sphinx
でMarkdown
を使う(
仮)
@r_rudi
Slide 2
Slide 2 text
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
をはじめよう」
の著者の一人
Slide 3
Slide 3 text
2015/11/25 Sphinx
でMarkdown
を使う(
仮)
https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 3/12
Markdown
今やMarkdown
全盛...
reStructuredText
は流行らない...
圧倒的敗北...
Sphinx
はreST
しか使えないから、
使えない...
そんなことを考えていた時期が俺にもありました。
Slide 4
Slide 4 text
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
が使えるようになった
Slide 5
Slide 5 text
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
Slide 6
Slide 6 text
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
'
,
}
Slide 7
Slide 7 text
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
で記述 ということも可能
Slide 8
Slide 8 text
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
先生に感謝
Slide 9
Slide 9 text
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)
Slide 10
Slide 10 text
2015/11/25 Sphinx
でMarkdown
を使う(
仮)
https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 10/12
問題点 / Problem
CommonMark
仕様のみ
:
+
1
:
とかない
テー
ブルがない
sphinx
のrole
やdirective
は使えない
拡張もできない
CommonMark
自体で拡張の議論はあるようす
議論紛糾で動きがなさそう
Slide 11
Slide 11 text
2015/11/25 Sphinx
でMarkdown
を使う(
仮)
https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 11/12
まとめ / Conclusion
Sphinx
でもmarkdown
を使えます
出力はSphinx
と変わりない
ただし、CommonMark
仕様のみ
Slide 12
Slide 12 text
2015/11/25 Sphinx
でMarkdown
を使う(
仮)
https://dl.dropboxusercontent.com/u/218108/sphinxcon2015/markdown.html#1 12/12