CODEWITHSUNDEEP
pythonoverloadingpython-sphinxrestructuredtextdocstring
David Hožič
David Hožič

Reputation: 255

Docstrings for overloaded functions with .. autofunction:: in Sphinx

I have an issue with using the Sphinx's .. autofunction:: directive on a function that has multiple @overload decorators.

While prototypes of the functions are included, the docstrings I want are not.

What it generates:

Generated

What I want is something like this: (Notice the docstring below the prototype):

Expected

My Sphinx code:

.. autofunction:: framework.add_object

Snippet of function code (Shortened):

@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
    # ...

Upvotes: 3

Views: 1318

Answers (1)

David Hožič
David Hožič

Reputation: 255

UPDATE: I didn't really find a way to achieve anything with an .. autofunction directive, however I made a decorator that marks functions/classes that are to be documented and I made a script that generates auto directives for the functions/classes.

One of the things the script also supports is parsing numpy styled docstrings and converts them into rst field lists and then creates a .. function:: name(params) -> return type directive.

Not exactly ideal but feel free to modify it.

Script: https://gist.github.com/davidhozic/6933a07b4ab9fa9c4d3e297eb5daa36e

Decorator: https://gist.github.com/davidhozic/bb954c2812dda2661f7ade24d5ba6dda


Example decorator usage: 
@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
    """
    ...

Script output:

----------------------------
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

Upvotes: 2

Related Questions