在 Sphinx 文档中包含文档字符串

Question

我想在我的 Sphinx 文档中仅包含特定函数的文档字符串。但是，似乎没有选项可以使用 http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

我已经尝试创建一个类，如在 Sphinx 文档中显示 *仅* 文档字符串？ 但我不确定这如何适合与模板一起使用。

我还尝试了 autodoc-process-docstring 事件处理程序，但没有成功。

因此，我的文档不显示（如当前所示）：

class module.MyClass(param)

    This is the class doc string

    my_method()

        This is my method doc string

我只想显示：

This is my method doc string

我当前在 .txt 文件中的模板是：

.. autoclass:: module.MyClass
    :members: my_method

Answer 1

在查看了源代码并进行了实验之后 - 以下是如何在 Sphinx 1.1 中执行此操作。

在您的 conf.py 文件中创建一个新的 MethodDocumenter 子类。在这里您可以设置一个新的“objtype”，确保文档字符串不缩进，并删除标题。

from sphinx.ext import autodoc

class SimpleDocumenter(autodoc.MethodDocumenter):
    objtype = "simple"

    #do not indent the content
    content_indent = ""

    #do not add a header to the docstring
    def add_directive_header(self, sig):
        pass

然后确保使用以下函数将其添加到可用的文档记录器中（同样在 conf.py 中）：

def setup(app):
    app.add_autodocumenter(SimpleDocumenter)

然后，当您只想显示方法的文档字符串时，请在 .txt 或 .rst 文件中使用以下格式。只需在你的 objname 前面加上 auto 前缀即可。

.. autosimple:: mod.MyClass.my_method

Answer 2

我在 Sphinx 5.3 中使用了这种方法。

如果您不想覆盖类 API 文档的默认 MethodDocumenter，则还需要覆盖以下 can_document_member 并将其设置为 False。生成的类如下所示

class SimpleDocumenter(autodoc.MethodDocumenter):
"""
Reference a class or method docstring only.
see https://stackoverflow.com/a/7832437/5726546
"""
  objtype = "simple"

    content_indent = ""

    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        return False

    # do not add a header to the docstring
    def add_directive_header(self, sig: str) -> None:
        pass

设置和指令与 geographika 的回答中的相同。