docstrings/sphinx: Support "Examples" sections about griffe HOT 4 CLOSED

Closing for cleanup, but if you'd like to work on this, just ask and I'll reopen!

from griffe.

Hi @pawamoy. The only clear example I've found was last updated in 2014 and isn't part of official documentation and uses :Example: singular rather than plural.

https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html#template-py-source-file

A relevant snippet:

def function1(self, arg1, arg2, arg3):
    """returns (arg1 / arg2) + arg3

    This is a longer explanation, which may include math with latex syntax
    :math:`\\alpha` (abbridged for ease of example):

    :param arg1: the first value
    :param arg2: the first value
    :param arg3: the first value
    :type arg1: int, float,...
    :type arg2: int, float,...
    :type arg3: int, float,...
    :returns: arg1/arg2 +arg3
    :rtype: int, float

    :Example:

    >>> import template
    >>> a = template.MainClass1()
    >>> a.function1(1,1,1)
    2
    """
    return arg1/arg2 + arg3

Note: it renders >>> in an on/off way in html for ease of copying.

from griffe.

Two more:

• :Example: in a Sphinx napolean test
• :example: in a queirozf post

from griffe.

Thanks @griff-rees!

Note that in the Sphinx link, :Example: is in a Google style test and is actually used to test that it is not recognized and rendered in any useful way: the expected result is the exact same docstring.

I'll leave this issue closed for now, because I don't plan on working on it (and you switched to the Google-style anyway 👍), but if anyone would like to work on it, just let me know.

from griffe.