Help us understand the problem. What is going on with this article?

SphinxでMarkdownをHTMLに変換する

More than 1 year has passed since last update.

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

参考

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした