Sphinxにおけるデフォルトの言語は、reStructuredTextであるが、Markdownに比べ記法が複雑で改めてそれを覚えるのも面倒で、多少知識のあるhtmlを使った方が良い位である。
そこで、MarkdownをSphinxで使えないか調べてみた。
Sphinxの本家本元のドキュメントには、Markdownを使うための記述がある（Markdown参照）が、その具体的な使用方法はMySTに聞けとそっけない。
情報も少ないので、当該サイトの手順に則り作業を進める。
1. MyST のインストール
|
|
conda install -c conda-forge myst-parser |
2. ドキュメントのソースの準備
適当なディレクトリを作成し、その中に次によりドキュメントのソースを作る。
3. conf.py の編集
conf.py に次の行を追加する。
|
|
extensions = ["myst_parser"] |
以上で、準備は完了。
いざ、Get started with MyST in Sphinxを参考にページを作ろうと、
|
|
# My nifty title Some **text**! |
をmyfile.mdとして作ったものの、次のファイル名をどうするか？
説明は以下の通りであるが、英語力がないのか、技術力が不足しているのか理解ができない。
In the “main document” of your Sphinx project (the landing page of your Sphinx documentation), include myfile.md in a toctree directive so that it is included in your documentation:
概ね、Sphinxプロジェクトの「メインドキュメント」（Sphinxドキュメントのランディングページ）のtoctree ディレクティブに myfile.md を指定せよ言っていると思うが、ランディングページとは何者か？？？
このディレクティブは、rst（reStructuredTextの略）のものなので index.rst に記述しても、myfile.md は拡張子が違うので無視されてしまう。
index.mdとすると、markdownにディレクティブなどと言う概念がないので、”.. toctree::” は単なる文字列として扱われてしまうのみ。
そこでいろいろ調た結果分かったことは、Markdown 拡張版（？）の “MyST” を使用するということだった。
結論、index.md に次のように記述する。
|
|
```{toctree} --- caption: Episodes maxdepth: 2 --- myfile ``` |
これで、今日一日を棒に振ってしまった。
参考：https://coderefinery.github.io/sphinx-lesson/toctree/