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

Question

我希望在我的Sphinx文档中仅包括特定函数的文档字符串。然而，似乎没有选项可以仅显示这些详细信息，而不使用相关的类和函数定义，该选项请参考http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html 我尝试按照Show *only* docstring in Sphinx documentation?中所述创建一个类，但我不确定它如何与模板配合使用。

我还尝试了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

- geographika

Answer 1

在查看源代码并进行实验后 - 这是如何在Sphinx 1.1中完成它的方法。

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

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

- geographika

Answer 2

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

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

class SimpleDocumenter(autodoc.MethodDocumenter):
"""
Reference a class or method docstring only.
see https://dev59.com/y1zUa4cB1Zd3GeqP2mKW#7832437
"""
  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的答案中相同。

- Sigmatics