如何在 Sphinx 文档中的某些特定功能后插入图像？

Question

我是 Sphinx 的新手。我使用 autodoc 生成了 .rst 个文件。以下是模块之一的 .rst 文件：

Building things
=====================

Actions
----------------------------------

.. automodule:: acat.build.actions
    :members: func1, func2, func3
    :undoc-members:
    :show-inheritance:

Patterns
----------------------------------

.. automodule:: acat.build.patterns
    :members: func4, func5
    :undoc-members:
    :show-inheritance:

Orderings
----------------------------------

.. automodule:: acat.build.orderings
    :members: func6
    :undoc-members:
    :show-inheritance:

现在我想在func1、func3和func5之后插入图片，我知道可以通过

嵌入图片

.. image:: func1_example.png

但是我应该把这些行放在哪里才能使图像显示在相应函数的正下方？

Answer 1

假设您有 1 个模块，其中包含 2 个函数和 3 个文档字符串，例如：

acat.build.actions.py

"""
The module docstring.
"""

def func1():
"""
Docstring of func1.
"""


def func2():
"""
Docstring of func2.
"""

为了准确地将图像插入到您想要的位置，您必须在 .rst 文件中的确切位置声明图像。所以你会这样写acat.build.actions.rst：

Building things
=====================

Actions
----------------------------------

.. automodule:: acat.build.actions
    :members:
    :exclude-members: func1
    :undoc-members:
    :show-inheritance:
    
    .. autofunction:: func1
        
        You can write some text here.
        
        .. image:: func1_example.png 

您使用 :exclude-members: func1 选项从模块中明确排除 func1 因为您想在其正下方包含图像。这允许您以自定义方式编写 func1 的文档，.. autofunction:: directive 将从 .py 文件中提取 func1 的文档字符串，但您可以编写 reStructuredText你想在里面。如果您想为更多功能执行此操作，请应用相同的技术。