python - 如何在 Markdown 文件中为 Sphinx 使用 automodule 或 autoclass？

Question

据我了解，Sphinx 可选择支持 markdown 或 .md 文件，这对我的补充文档非常有用。我想做的是在 markdown 文件中使用 autoclass 或 automodule 标签。

通常，在 .rst 文件中，如果我这样做的话

.. autoclass:: my.module.SomeClass
    :members:

它将自动提取所有文档字符串并创建文档。是否可以在 .md 文件中使用它？目前，当我尝试这样做时，生成的文档仅包含预期的 .. autoclass:... 。

我的conf.py是

extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "recommonmark"]
source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

由于阅读文档兼容性，我确实考虑了 mkdocs，但它不提供类似 autodoc 的功能。为了实现这一目标，我对任何其他库都非常开放(不必与 RTD 兼容)。

Answer 1

使用MyST

pip install myst-parser

将此扩展添加到您的 sphinx 配置中:

extensions = [..., "myst_parser"]

在 ``` block 内将 {eval-rst} 与 autoclass 角色一起使用

```{eval-rst}  .. autoclass:: my.module.SomeClass:members:```

Old, deprecated way

This might require using AutoStructify of Recommonmark, namely the RST embedding feature.

With it, you'd add the following to your markdown:

 ```eval_rst
 .. autoclass:: my.module.SomeClass
 :members:
 ```