docstrings/sphinx: Support "Examples" sections

[pawamoy]

Is your feature request related to a problem? Please describe.
The goal is to have a common set of features between all parsers.

Describe the solution you'd like
The Sphinx parser should be able to parse "Examples" sections, if it makes any sense.

[pawamoy]

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

[griff-rees]

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.

[griff-rees]

Two more:

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

[pawamoy]

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.