ドキュメント生成の前処理でテキストを任意変換するSphinx拡張

前提

最近、Sphinxで文書作成しています。

• restructuredTextより、markdownでゴリゴリ書きたい
• 公式ドキュメントによるとcommonMark使えばいけるが、Table使えない
• 「いいライブラリあるやんけ！」← MarkdownとreStructuredTextを単一ファイルに混ぜ書きできるM2Rの紹介（Sphinx拡張対応）

ということで一旦解決したのだが、PlantUMLを使う際にVSCode上でプレビューできないのがストレスになってきた。

やりたいこと

make htmlする時に、

```plantuml

の囲みを

.. uml::

に自動変換したい。

方針

公式ドキュメント内に、イベント実装方法あり。

• 「Sphinx.connect(event, callback)」でイベントに対するコールバック関数を指定する模様。
• 各種イベント定義は「Sphinx core events」にあり。
• 今回のように素のテキストを変換したい場合、「source-read(app, docname, source)」が使えそう。

拡張プラグイン実装

こんな感じで書いてみた。

uml_change.py

def uml_change(app, docname, source):  
    umlFlg = False
    lines = []
    for line in source[0].split("\n"):
        if umlFlg:
            if line.strip() == "```":
                # 囲みの終端が来たら削除する
                line = ""
                umlFlg = False
            else:
                # 囲みの中はインデントする
                line = "    " + line

        ### markdown表記をreST表記に変換
        if line.strip() == "```plantuml":
            line = ".. uml::"
            umlFlg = True

        lines.append(line)

    source[0] = "\n".join(lines)

def setup(app):  
    app.connect("source-read", uml_change)  

conf.py設定

conf.py に以下の記載を追加する。

conf.py

import sys
import os
sys.path.append(os.path.abspath("./bin")) #フォルダ名は一例です

上記スクリプトを指定したフォルダに格納する（上記例で言えばbin配下）。

extensionsに作成したプラグイン名を追加。

conf.py

extensions = ['uml_change']

make html やってみて、uml画像が表示されていたら成功。

補足

この方法の応用で色々任意の前処理が書けるはず。markdownのリンク形式をrestructuredTextの書式に変換する、等。