Sphinx で markdown を扱う (無理やり日本語も) #Markdown

Markdown形式（そこまで複雑でないが長いもの）で書いたドキュメントを、HTMLにしてS3でホストしたりPDFで配布したい

のでSphinxを試しました。
（プログラミング始め1年あまり、Pythonしか手に馴染んでる言語がない、というのもありますが……）

形にはなっているものの、少し見栄えが悪いのが難点で、最適解模索中です。

インストール

pip install sphinx commonmark==0.5.4 recommonmark

Sphinx 本体と、Markdown（正確にはcommonmark）形式のパーサー、Sphinxで扱う形式への変換モジュールをインストールします。

2017/3 初旬現在、commonmarkの最新版とrecomonmarkの相性が悪いため、前のバージョンを指定してインストールをします。

参考:SphinxでMarkdownを使うときに注意すること

設定

ソースディレクトリに置かれるconf.pyに記述を追加します。

from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify

...

# mdファイルがある場合はパーサー変更
source_suffix = ['.rst', '.md']
source_parsers = {
    '.md': CommonMarkParser,
}

...

# recommonmark の拡張利用
github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

拡張機能の詳細についてはこちら。

Recommonmark Document

より便利に扱いたい場合こちらの記事が大変参考になります。

Sphinxを便利にして、みんなに使ってもらいたい

後は、ソースディレクトリにindex.rstのような起点になるrstファイルを配置し、そこにビルド元のmdファイルのファイル名を書き連ねればMarkdown形式からビルドを行えるはずです。

画像の貼り込み

~~突き当たっている課題その１です。~~
環境インストールし直しで解決しました、下記は参考まで

画像の貼り込みが
![title](images/image.png)
~~でできれば良いのですが、うまくいかなかったので~~
上手くいきました、上記で大丈夫です。

```eval_rst
.. figure:: images/image.png
``` `

日本語セクションにアンカーが貼られるようにする

突き当たってる課題その2です。
recommonmarkがacsii文字以外はエスケープしてしまうようで、そのままだとうまくリンクが貼れません。
場当たり対応ですが、URLエンコードを施すようrecommonmarkのparser.pyを書き換え、リンクが貼られるようにしました。

parser.py

from future.moves.urllib.parse import quote

...

# name = nodes.fully_normalize_name(title_node.astext())  # コメントアウト
name = quote(' '.join(block.strings))  # 2017/03/09現在pip でインストールできる0.4.0だと110行目

※直接触るのは怖いのでdockerを利用しています。試される場合はdockerやpyvenvをおすすめします。

ただこのやり方だと、%が-へとさらにエスケープされるために-ばかりの美しくないリンクが生成されてしまいます（もはや乱数を入れた方が良いかもしれません）。
とりあえず動いているように見えますが、副作用があるやもです。

より良い方法あればご共有いただければ(_ _)