ドキュメントの構文:ドキュメントを作成するためのマークダウン構文とmyST構文とrst構文#

Pythonのドキュメントを作成するためによく使われる構文は3つあります:

  1. markdown: Markdownは習得しやすいテキスト構文です。 これはJupyter Notebooksで使われるデフォルトの構文です。 マークダウンをhtmlとしてレンダリングするためのツールをSphinxのウェブサイトに追加することができます。 しかし、マークダウンを使ってドキュメントを書くことには限界があります。 例えば、ドキュメントにリファレンスや色付きのカラー出力ブロック、その他のカスタム要素を追加したい場合、 myST または rST を使用する必要があります。

  2. rST (ReStructured Text):。 rSTは、sphinxがサポートするネイティブの構文です。rSTは、長年ドキュメントに使用されてきたデフォルトの構文です。しかし、近年、mySTがその柔軟性から、ドキュメンテーションによく使われるようになりました。

  3. myST: myST is a combination of markdown and rST syntax. It is a nice option if you are comfortable writing markdown. myst is preferred by many because it offers both the rich functionality of rST combined with a simple-to-write markdown syntax.

上記のどの構文を使ってもよいですが、 myST を使うことをお勧めします:

  • よりシンプルな構文であるため、習得しやすいです;

  • 上記のようにシンプルにすることで、より多くの人があなたのドキュメントに貢献しやすくなります。

  • README.mdファイルなど、Pythonパッケージのコアとなるテキストファイルのほとんどは、すでに .md 形式になっています。

  • GitHub と Jupyter Notebooks はMarkdownをサポートしており、科学的なエコシステムでより広く使われています。

Tip

mySTとrstを迷っているなら、 myST の方がより多くの人が貢献しやすいと感じるかもしれません。