12

私は Sphinx を使用して Python プロジェクトを文書化しています。docstrings で Markdown を使用して書式を設定したいと思います。拡張機能を使用しても、ドキュメント文字列ではなく、手動で記述されたファイルのみをカバーします。recommonmark.md

私は拡張機能autodocでnapoleonとを使用しています。recommonmark

docstring でsphinx 解析マークダウンを作成するにはどうすればよいですか?

4

4 に答える 4

21

Sphinx の Autodoc 拡張機能はautodoc-process-docstring、ドキュメント文字列を処理するたびに名前付きのイベントを発行します。そのメカニズムにフックして、構文を Markdown から reStructuredText に変換できます。

残念ながら、Recommonmarkは Markdown から reST へのコンバーターを公開していません。これは、解析された Markdown をDocutilsオブジェクトに直接マップします。つまり、Sphinx自体が reStructuredText から内部的に作成するのと同じ表現です。

代わりに、プロジェクトでの変換にCommonmarkを使用しています。高速だからです —たとえば、 Pandocよりもはるかに高速です。変換はその場で行われ、各ドキュメント文字列を個別に処理するため、速度は重要です。それ以外は、任意の Markdown-to-reST コンバーターで十分です。M2R2は 3 番目の例です。これらの欠点は、ドキュメントの他の部分への相互参照など、Recommonmark の構文拡張をサポートしていないことです。基本的なマークダウンだけです。

Commonmark doc-string コンバーターをプラグインするには、パッケージがインストールされていることを確認し ( pip install commonmark)、以下を Sphinx の構成ファイルに追加しますconf.py。

import commonmark

def docstring(app, what, name, obj, options, lines):
    md  = '\n'.join(lines)
    ast = commonmark.Parser().parse(md)
    rst = commonmark.ReStructuredTextRenderer().render(ast)
    lines.clear()
    lines += rst.splitlines()

def setup(app):
    app.connect('autodoc-process-docstring', docstring)

一方、Recommonmark は2021 年 5 月に廃止されました。より機能豊富な Markdown パーサーであるSphinx 拡張機能MySTは、 SphinxおよびRead-the-Docs が推奨する代替品です。MySTはドキュメント文字列での Markdownもまだサポートしていませんが、上記と同じフックを使用して、Commonmark を介して限定的なサポートを得ることができます。

ここで概説したアプローチに代わる可能性のある方法は、 MkDocsをMkDocStringsプラグインと共に使用することです。これにより、Sphinx と reStructuredText がプロセスから完全に排除されます。

于 2019-06-03T13:11:07.673 に答える