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

Question

我是狮身人面像的新手。我使用自动文档生成了.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。如果您想为更多功能执行此操作，请应用相同的技术。