SphinxでMarkdownをHTMLに変換する

[sphinx-with-markdown](https://github.com/unhurried/sphinx-with-markdown)（Markdownで記述したドキュメントをSphinxでHTMLに変換するプロジェクト）の検討をしたときのメモ

### 検討メモ

#### Markdown対応

##### インストール

[recommonmark](https://recommonmark.readthedocs.io/en/stable/)を.mdファイルのパーサーとして登録する。


```shell
pip install recommonmark
```

conf.py

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

Markdown中にreStructuredTextを埋め込む `eval_rst` や、コードブロックのシンタックスハイライトを使うために、conf.pyに以下の記述を追加して、[AutoStructify](https://recommonmark.readthedocs.io/en/latest/auto_structify.html)コンポーネントを有効化する。

```python
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](https://github.com/ryanfox/sphinx-markdown-tables)ををインストールする。

```shell
pip install sphinx-markdown-tables
```

conf.py

```python
extensions = [
    'sphinx_markdown_tables',
]
```

#### 国際化（多言語化）

Sphinxのgettextベースの多言語サポート機能（[sphinx-intl](http://www.sphinx-doc.org/ja/stable/intl.html)）を使う。

##### インストール

```shell
pip install sphinx-intl
```

##### 使い方

```shell
# ソースから翻訳可能なメッセージを{ビルドディレクトリ}/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](https://poedit.net/)が使いやすい。

##### 参考

* [GetTextを用いたローカライズ方法](https://conyac.cc/ja/business/columns/localization_guide_po_pot)

#### HTML用テーマ

[sphinx-themes.org](https://sphinx-themes.org/)に様々なテーマがまとめられている。

sphinxを紹介している記事を見てみると[Read the Docs](https://sphinx-rtd-theme.readthedocs.io/en/stable/)テーマが人気があるようである。

#### Dockerイメージ

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

- [hnakamur/sphinx](https://hub.docker.com/r/hnakamur/sphinx/)
  - sphinxのバージョンが2.0.1１（最新版は2.1.2）で止まっている。
- [docker-sphinx-rtd-theme](https://hub.docker.com/r/suttang/sphinx-rtd-theme)
  - sphinxのバージョンは指定されていないため、自分でビルドすれば使えそう。
  - Pythonのバージョンが若干古い（3.6）く、今回使いたいsphinx-intlは入っていない。
- [plaindocs/docker-sphinx](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](https://sphinx-users.jp/reverse-dict/system/orphan.html)を記述すればよい。

#### 使えそうなパッケージ

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



### 参考

- [公式ドキュメント](http://www.sphinx-doc.org/ja/stable/contents.html)
- [Sphinxを便利にして、みんなに使ってもらいたい](https://qiita.com/pashango2/items/d1b379b699af85b529ce)