SphinxでMarkdownをHTMLに変換する

sphinx-with-markdown（Markdownで記述したドキュメントをSphinxでHTMLに変換するプロジェクト）の検討をしたときのメモ

検討メモ

Markdown対応

インストール

recommonmarkを.mdファイルのパーサーとして登録する。

pip install recommonmark

conf.py

source_suffix = ['.rst', '.md']
source_parsers = {
   '.md': 'recommonmark.parser.CommonMarkParser',
}

Markdown中にreStructuredTextを埋め込む eval_rst や、コードブロックのシンタックスハイライトを使うために、conf.pyに以下の記述を追加して、AutoStructifyコンポーネントを有効化する。

from recommonmark.transform import AutoStructify
def setup(app):
    app.add_config_value('recommonmark_config', {
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

recommonmarkはMarkdownの表組み記法に対応していないため、sphinx_markdown_tablesををインストールする。

pip install sphinx-markdown-tables

conf.py

extensions = [
    'sphinx_markdown_tables',
]

国際化（多言語化）

Sphinxのgettextベースの多言語サポート機能（sphinx-intl）を使う。

インストール

pip install sphinx-intl

使い方

# ソースから翻訳可能なメッセージを{ビルドディレクトリ}/gettextにpotファイルとして展開する
make gettext
# potファイルからpoファイルを生成（更新）して{ソースディレクトリ}/localeに出力する
sphinx-intl update -p build/gettext -l en

# 生成されたpoファイルを編集する

# 言語を指定して翻訳されたドキュメントを生成する
make -e SPHINXOPTS="-D language='en'" html

ドキュメントを更新したときも同様の手順でpoファイルを更新できる。

POファイルの編集

無償版は多少の機能制限があるが、PoEditが使いやすい。

参考

GetTextを用いたローカライズ方法

HTML用テーマ

sphinx-themes.orgに様々なテーマがまとめられている。

sphinxを紹介している記事を見てみるとRead the Docsテーマが人気があるようである。

Dockerイメージ

sphinxをインストールするイメージはDockerHubにいくつか登録されているが、あまり積極的にメンテナンスされていないため、python公式イメージ（alpine）から作るのがよさそう。

hnakamur/sphinx
- sphinxのバージョンが2.0.1１（最新版は2.1.2）で止まっている。
docker-sphinx-rtd-theme
- sphinxのバージョンは指定されていないため、自分でビルドすれば使えそう。
- Pythonのバージョンが若干古い（3.6）く、今回使いたいsphinx-intlは入っていない。
plaindocs/docker-sphinx
- 4年前に1度だけプッシュされたもの。ubuntuベースのためイメージサイズが大きい。

既知の問題

Markdownのリスト記法 * item をHTMLに変換すると <li><p>item</p></li> となり、余計なp要素が追加される。（結果として、Read the Docsテンプレートでは余計なマージンが出力される。）
poファイル出力時にインライン装飾が無効化されため、翻訳に手作業でreST記法で装飾を入れなおす必要がある。

その他Sphinxに関するTipsなど

toctreeの警告回避

どのtoctreeにも含まれないドキュメントがあると以下の警告が出力される。

checking consistency... C:\Users\takayuki\Desktop\sx\source\test.md: WARNING: document isn't included in any toctree

この警告を抑制するにはファイル先頭にorphanを記述すればよい。

使えそうなパッケージ

ePub形式で出力する：pip install Pillow
ファイルを監視して再ビルドする：pip install sphinx-autobuild