Sphinx で markdown のファイルを include する方法で躓く

Python のプロジェクトで sphinx の autodoc を使おうと努力？していて、 プロジェクトの文書は docs ディレクトリに入れている。

プロジェクトトップの README.md というファイルに 概要を記載することにしているのだが、 こいつを sphinx の文書に include させたくなったのだが、 markdown を変換してくれない、という問題が発生した。 extension には myst_parser を加えている。

REASME.rst にするとか、docs ディレクトリにコピーして使うとかで問題ないのだが、 markdown の方が市民権が強いみたいだし、釈然としない。で、調べてみると、 以下の記事をみつけた。

• sphinx-doc/sphinx#7000 Support for files outside Sphinx project (README.md in…

プロジェクトトップのファイルを autodoc で直接利用する方法について、 昔から話はあるようだが、 markdown ファイルの include には、課題が残っていたようだ。

解決方法は、以下のふたつ。

1. markdown を reStructured に変換する m2r2 という extension を追加して、 mdinclude というディレクティブを使う。

   .. mdinclude:: ../README.md
   

   • GitHub - CrossNox/m2r2: Markdown to reStructuredText converter

1. extension に myst_parser 追加して、 include 時に parser を指定する。ただし、新しいバージョンでないとだめ。

   .. include:: ../README.md
      :parser: myst_parser.sphinx_
   

   • GitHub - executablebooks/MyST-Parser: An extended commonmark compliant parser…

両方とも、markdown ファイルを include してくれたので、よしとしよう。

しかし、肝心なのは中身なのに、それがまだまだ。 python は、gpx がらみがほとんどで、自転車封印2.5年越えで、 モチベーションが既に維持できてない。