python - Sphinx 中带有 .. autofunction::的重载函数的文档字符串

Question

在具有多个 @overload 装饰器的函数上使用 Sphinx 的 .. autofunction:: 指令时遇到问题。

虽然包含了函数的原型(prototype)，但没有包含我想要的文档字符串。

它生成什么:

我想要的是这样的:(注意原型(prototype)下面的文档字符串):

我的 Sphinx 代码:

.. autofunction:: framework.add_object

函数代码片段(缩短):

@overload
async def add_object(obj: Union[guild.USER, guild.GUILD]) -> None: 
    """
    docstring 1
    """
    ...
@overload
async def add_object(obj: Union[message.DirectMESSAGE, message.TextMESSAGE, message.VoiceMESSAGE], snowflake: Union[int, guild.GUILD, guild.USER, dc.Guild, dc.User]) -> None:
    """
    docstring 2
    """
    ...
async def add_object(obj, snowflake=None):
    # Implementation
    # ...

Answer 1

更新: 我并没有真正找到一种方法来使用 .. autofunction 指令实现任何目标，但是我制作了一个装饰器来标记要记录的函数/类，并且我制作了一个为以下内容生成自动指令的脚本函数/类。

脚本还支持的功能之一是解析 numpy 样式的文档字符串并将它们转换为第一个字段列表，然后创建一个 .. function::name(params) -> return type 指令。

不太理想，但可以随意修改。

脚本:https://gist.github.com/davidhozic/6933a07b4ab9fa9c4d3e297eb5daa36e

装饰器:https://gist.github.com/davidhozic/bb954c2812dda2661f7ade24d5ba6dda

装饰器用法示例:

@overload
@misc.doc_category("Shilling list modification", True) # <----- The decorator
async def add_object(obj: Union[guild.USER, guild.GUILD]) -> None:
    """

    Adds a guild or an user to the daf.

    Parameters
    -----------
    obj: Union[guild.USER, guild.GUILD]
        The guild object to add into the daf.

    Raises
    ----------
    ValueError
        The guild/user is already added to the daf.
    TypeError
        The object provided is not supported for addition.
    TypeError
        Invalid parameter type.
    Other
        Raised in the obj.initialize() method
    """
    ...

脚本输出:

----------------------------
Shilling list modification
----------------------------

add_object
========================
.. function:: daf.core.add_object(obj: typing.Union[daf.guild.USER, daf.guild.GUILD]) -> None
    
    Adds a guild or an user to the daf.
    
    :Parameters:
        - obj: Union[guild.USER, guild.GUILD]
              The guild object to add into the daf.
    
    :Raises:
        - ValueError
              The guild/user is already added to the daf.
        - TypeError
              The object provided is not supported for addition.
        - TypeError
              Invalid parameter type.
        - Other
              Raised in the obj.initialize() method