はじめに #
SphinxでMarkdownの拡張言語であるMyST (Markedly Structured Text) を導入する方法をまとめました。
SphinxはPython製のドキュメント生成ツールです。Sphinxは標準でReST (reStructuredText) と呼ばれるマークアップ言語をサポートしています。SphinxでMarkdownまたはMySTを導入する場合、myst-parserというプラグインを導入します
この記事では、Sphinxとmyst-parserを導入する方法と、MySTによる記事の作成方法を述べます。
ReSTとMySTについて #
ReSTは表現力の高いマークアップ言語であり、標準的なMarkdownではできない以下のような記述が可能です（ただし、一部のMarkdown方言はサポートしているかもしれません）。
- 任意の場所への目次 (
toctree) の生成 - 脚注 (
footnote) - 画像の左寄せ・右寄せ
- テーブル（表）の結合セル
しかし、Markdownを既に習得しているユーザにとっては、ReSTを勉強するのは手間です。そこで、Sphinxにプラグインを追加し、Markdown方言であるMySTで記事を作成できるようにします。
MySTはCommonMarkを拡張した言語（上位セット）です（CommonMarkはMarkdownの仕様を明確にした言語で、2014年に開発されました。以降では、MarkdownはCommonMarkのことを指します）。MySTでは、ReST形式で表現できることの大半を表現できます。
なお、かつてはrecommonmarkという、SphinixでCommonMarkを利用できるプラグインがありました。しかし、現在は開発が停止されており、使用は推奨されていません。
環境 #
OSはWindows 10 Home Ver. 21H1です。
- Python v3.8.5
- Sphinx v4.4.0
- myst-parser v0.17.0
Sphinxとmyst-parserのインストール #
Pythonは既にインストールされているものとして、Sphinxとmyst-parserをインストールします。Condaとpipのどちらでもインストール可能ですが、myst-parserではCondaが推奨されています。
Conda環境では以下を実行します。-cオプションによって、インストール元のチャンネルを指定します。
conda install -c anaconda sphinx
conda install -c conda-forge myst-parser
pipの場合は以下を実行します。
pip install sphinx
pip install myst-parser
プロジェクトテンプレートの作成 #
適当な空フォルダを作成し、sphinx-quickstartコマンドを実行してプロジェクトテンプレートを作成します。詳細は以下の記事を参考にしてください。
設定ファイルの編集 #
Sphinxの設定ファイルconf.pyを開き、extensionsにmyst-parserを追加します。
extensions = ["myst_parser"]
これによって、SphinxはReST (.rst) とMarkdown (.md) の両方を扱えるようになります（ファイルの形式は拡張子で判定されます）。
Markdownファイルの作成とビルド #
Markdownファイルを追加します。index.rstと同じフォルダにtest.mdというファイルを作成し、中身を以下のように書きます。
# MyST Test
Hello, MyST.
> Blockquote
1. spam
1. ham
1. eggs
次に、index.rstを開き、以下のようにtest.mdを追加します。ここで、test.mdとtoctreeの先頭位置を揃えるようにインデントが必要です。index.rstはビルド後にindex.htmlに変換されるファイルです。また、toctreeは目次を生成するディレクティブ（指示）です。
.. toctree::
:maxdepth: 2
:caption: Contents:
test.md
上記のように追記することにより、test.mdがドキュメントに追加されたことをSphinxに教えます。
最後に、以下のコマンドを実行してHTMLファイルをビルドします。
.\make.bat html
コマンドの実行後、build/html/test.htmlというファイルが生成されているはずです。これを開くと、MarkdownファイルをHTMLファイルに変換できたことが確認できます。
まとめ #
SphinxでMarkdownの拡張言語であるMyST (Markedly Structured Text) を導入する方法をまとめました。 MyST独自の記法については、以下の記事でまとめています。 SphinxでMarkdown拡張言語のMySTを扱う – Helve Tech Blog
