- Markdown形式（そこまで複雑でないが長いもの）で書いたドキュメントを、HTMLにしてS3でホストしたりPDFで配布したい
のでSphinxを試しました。
（プログラミング始め1年あまり、Pythonしか手に馴染んでる言語がない、というのもありますが……）
形にはなっているものの、少し見栄えが悪いのが難点で、最適解模索中です。
インストール
pip install sphinx commonmark==0.5.4 recommonmark
Sphinx 本体と、Markdown（正確にはcommonmark）形式のパーサー、Sphinxで扱う形式への変換モジュールをインストールします。
2017/3 初旬現在、commonmarkの最新版とrecomonmarkの相性が悪いため、前のバージョンを指定してインストールをします。
設定
ソースディレクトリに置かれる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)
拡張機能の詳細についてはこちら。
より便利に扱いたい場合こちらの記事が大変参考になります。
後は、ソースディレクトリにindex.rstのような起点になるrstファイルを配置し、そこにビルド元のmdファイルのファイル名を書き連ねればMarkdown形式からビルドを行えるはずです。
画像の貼り込み
突き当たっている課題その１です。
環境インストールし直しで解決しました、下記は参考まで
画像の貼り込みが
でできれば良いのですが、うまくいかなかったので
上手くいきました、上記で大丈夫です。
```eval_rst
.. figure:: images/image.png
``` `
日本語セクションにアンカーが貼られるようにする
突き当たってる課題その2です。
recommonmarkがacsii文字以外はエスケープしてしまうようで、そのままだとうまくリンクが貼れません。
場当たり対応ですが、URLエンコードを施すようrecommonmarkの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をおすすめします。
ただこのやり方だと、%が-へとさらにエスケープされるために-ばかりの美しくないリンクが生成されてしまいます（もはや乱数を入れた方が良いかもしれません）。
とりあえず動いているように見えますが、副作用があるやもです。
より良い方法あればご共有いただければ(_ _)