sphinx style

[KristoforMaynard]

Formatting for sphinx sections is a little more subtle than the current implementation from PR #27 would indicate. I ran some Google-styled docstrings through Napoleon (the engine that sphinx uses to convert Numpy/Google styles to rst) to see how these sections should be formatted. I think it's important to conform to a standard before tagging the new sphinx-style for release (and what better standard than the one used by sphinx itself).

Below is a docstring that exercises all the section types that are supported by sphinx. Also, here are some todo lists to keep track of which sections still need work. I pushed a branch called sphinx to provide a place for further development.

Formatting

• [ ] Args
• [ ] Attributes
• [ ] Example
• [ ] Examples
• [ ] Keyword Args
• [ ] Methods
• [ ] Note
• [ ] Notes
• [ ] Other Parameters
• [ ] Returns
• [ ] Raises
• [ ] References
• [ ] See Also
• [ ] Warning
• [ ] Yield
• [ ] Other (Misc.)

Parsing

• [ ] Args
• [ ] Attributes
• [ ] Example
• [ ] Examples
• [ ] Keyword Args
• [ ] Methods
• [ ] Note
• [ ] Notes
• [ ] Other Parameters
• [ ] Returns
• [ ] Raises
• [ ] References
• [ ] See Also
• [ ] Warning
• [ ] Yield
• [ ] Other (Misc.)

Sample Google Docstring

"""quick summary

Longer summary here

Args:
    arg1(int): first argument
    arg2(int): second argument

Attributes:
    attrib1 (int): first attribute
    attrib2 (str): second attribute

Example:
    >>> print('ex 1')
    ex 1

Examples:
    >>> print('ex 2a')
    ex 2a

    >>> print('ex 2b')
    ex 2b

Keyword Args:
    kwarg1 (float): first optional kwarg
    kwarg2 (ndarray): second optional kwarg

Methods:
    meth1: first method
    meth2: second method

Note:
    A single note

Notes:
    * Note 2a

    * Note 2b

Other Parameters:
    other_param1 (int): other param1 description
    other_param2 (str): other param2 description

Returns:
    float: return description

Raises:
    ValueError: Something unexpected happened

References:
    ref 1
    ref 2

See Also:
    * :py:func:`load_swallow`: check out this function

Warning:
    Take note of this!

Yield:
    int: yield description

Other (Misc.):
    To the Eggplantmobile!

"""

Sphinx Result (using Napoleon)

"""quick summary

Longer summary here

:param arg1: first argument
:type arg1: int
:param arg2: second argument
:type arg2: int

.. attribute:: attrib1

   *int* -- first attribute

.. attribute:: attrib2

   *str* -- second attribute

.. rubric:: Example

>>> print('ex 1')
ex 1

.. rubric:: Examples

>>> print('ex 2a')
ex 2a

>>> print('ex 2b')
ex 2b

:keyword kwarg1: first optional kwarg
:kwtype kwarg1: float
:keyword kwarg2: second optional kwarg
:kwtype kwarg2: ndarray

.. method:: meth1

   first method

.. method:: meth2

   second method


.. note:: A single note

.. rubric:: Notes

* Note 2a

* Note 2b

:Other Parameters: * **other_param1** (*int*) -- other param1 description
                   * **other_param2** (*str*) -- other param2 description

:returns: return description
:rtype: float

:raises: :exc:`ValueError` -- Something unexpected happened

.. rubric:: References

ref 1
ref 2

.. seealso:: * :py:func:`load_swallow`: check out this function

.. warning:: Take note of this!

:Yields: *int* -- yield description

Other (Misc.):
    To the Eggplantmobile!
"""

[syffer]

I think it is even more complicated than that, as the configuration can change the sphinx output in Napoleon. The 'Attribute' section is an example of that, as it can be either 'ivar', or '.. attribute::' depending on the set of 'napoleon_use_ivar'

Some configuration can be found here : https://sphinxcontrib-napoleon.readthedocs.io/en/latest/

[ksdaftari]

@KristoforMaynard dont know if still actively maintaining library but wondering of likely hood of this being picked up. dont know if anything can learn from the auto docstring implementation like has been done for "sphinx" in https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring