LoginSignup
7

More than 3 years have passed since last update.

posted at

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

参考

HTML用テーマ

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

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

Dockerイメージ

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

  • hnakamur/sphinx
    • sphinxのバージョンが2.0.11(最新版は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

参考

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
What you can do with signing up
7