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が使いやすい。
参考
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