如何在降价文件中为 Sphinx 使用自动模块或自动类？

Question

我了解 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 兼容）持开放态度。

Answer 1

使用MyST

pip install myst-parser

将此扩展程序添加到您的 sphinx 配置中：

extensions = [..., "myst_parser"]

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

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

旧的、已弃用的方式

这可能需要使用 AutoStructify of Recommonmark, namely the RST embedding 功能。

有了它，您可以将以下内容添加到降价中：

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

Answer 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

Answer 3

如果您正在使用 MyST：

extensions = [
    'myst_parser',
    ...
]

您只需：

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

如何在降价文件中为 Sphinx 使用自动模块或自动类？

How can I use automodule or autoclass for Sphinx in a markdown file?

python

python-sphinx

autodoc

read-the-docs

使用MyST

旧的、已弃用的方式