如何在降价文件中为 Sphinx 使用 automodule 或 autoclass？答案

【问题标题】：How can I use automodule or autoclass for Sphinx in a markdown file?如何在降价文件中为 Sphinx 使用 automodule 或 autoclass？
【发布时间】：2020-03-15 15:19:10
【问题描述】：

我了解 Sphinx 可以选择支持 markdown 或 .md 文件，这对我的补充文档非常有用。我想做的是在降价文件中使用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 兼容）都非常开放。

【问题讨论】：

标签： python python-sphinx read-the-docs autodoc

【解决方案1】：

如果您使用的是MyST：

extensions = [
    'myst_parser',
    ...
]

您需要做的就是：

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

【讨论】：

【解决方案2】：

将“.md”添加到 source_suffix 列表对我有用：

在你的 conf.py 中：

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
source_suffix = ['.rst', '.md']

我正在使用 sphinx 2.1.2

【讨论】：

【解决方案3】：

这可能需要使用 Recommonmark 的AutoStructify，即RST embedding 功能。

使用它，您可以在降价中添加以下内容：

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

【讨论】：