IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

[Napoleon] Miscellaneous formatting fixes to napoleon example docstrings

Browse Source
This commit is contained in:
Rob Ruana 2015-06-14 13:32:04 -07:00
parent d5d6556a8a
commit 27be6614f7
2 changed files with 17 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/ext/example_google.py
View File

@ -50,7 +50,7 @@ def module_level_function(param1, param2=None, *args, **kwargs):
`PEP 484`_, though `PEP 484`_ conformance isn't required or enforced. `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
If \*args or \*\*kwargs are accepted, If \*args or \*\*kwargs are accepted,
they should be listed as \*args and \*\*kwargs. they should be listed as ``*args`` and ``**kwargs``.
The format for a parameter is:: The format for a parameter is::
@ -104,16 +104,16 @@ def example_generator(n):
"""Generators have a ``Yields`` section instead of a ``Returns`` section. """Generators have a ``Yields`` section instead of a ``Returns`` section.
Args: Args:
n (int): The upper limit of the range to generate, from 0 to `n` - 1 n (int): The upper limit of the range to generate, from 0 to `n` - 1.
Yields: Yields:
int: The next number in the range of 0 to `n` - 1 int: The next number in the range of 0 to `n` - 1.
Examples: Examples:
Examples should be written in doctest format, and should illustrate how Examples should be written in doctest format, and should illustrate how
to use the function. to use the function.
>>> print [i for i in example_generator(4)] >>> print([i for i in example_generator(4)])
[0, 1, 2, 3] [0, 1, 2, 3]
""" """
@ -142,6 +142,7 @@ class ExampleError(Exception):
code (int): Exception error code. code (int): Exception error code.
""" """
def __init__(self, msg, code): def __init__(self, msg, code):
self.msg = msg self.msg = msg
self.code = code self.code = code
@ -170,6 +171,7 @@ class ExampleClass(object):
https://www.python.org/dev/peps/pep-0484/ https://www.python.org/dev/peps/pep-0484/
""" """
def __init__(self, param1, param2, param3): def __init__(self, param1, param2, param3):
"""Example of docstring on the __init__ method. """Example of docstring on the __init__ method.
@ -197,11 +199,11 @@ class ExampleClass(object):
self.attr4 = ['attr4'] self.attr4 = ['attr4']
self.attr5 = None self.attr5 = None
"""Optional[str]: Docstring *after* attribute, with type specified""" """Optional[str]: Docstring *after* attribute, with type specified."""
@property @property
def readonly_property(self): def readonly_property(self):
"""str: Properties should be documented in their getter method""" """str: Properties should be documented in their getter method."""
return 'readonly_property' return 'readonly_property'
@property @property

16
doc/ext/example_numpy.py
View File

@ -62,8 +62,8 @@ def module_level_function(param1, param2=None, *args, **kwargs):
Parameter types -- if given -- should be specified according to Parameter types -- if given -- should be specified according to
`PEP 484`_, though `PEP 484`_ conformance isn't required or enforced. `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
If \*args or \*\*kwargs are accepted, they If \*args or \*\*kwargs are accepted,
should be listed as \*args and \*\*kwargs. they should be listed as ``*args`` and ``**kwargs``.
The format for a parameter is:: The format for a parameter is::
@ -129,19 +129,19 @@ def example_generator(n):
Parameters Parameters
---------- ----------
n : int n : int
The upper limit of the range to generate, from 0 to `n` - 1 The upper limit of the range to generate, from 0 to `n` - 1.
Yields Yields
------ ------
int int
The next number in the range of 0 to `n` - 1 The next number in the range of 0 to `n` - 1.
Examples Examples
-------- --------
Examples should be written in doctest format, and should illustrate how Examples should be written in doctest format, and should illustrate how
to use the function. to use the function.
>>> print [i for i in example_generator(4)] >>> print([i for i in example_generator(4)])
[0, 1, 2, 3] [0, 1, 2, 3]
""" """
@ -177,6 +177,7 @@ class ExampleError(Exception):
Numeric error code. Numeric error code.
""" """
def __init__(self, msg, code): def __init__(self, msg, code):
self.msg = msg self.msg = msg
self.code = code self.code = code
@ -208,6 +209,7 @@ class ExampleClass(object):
https://www.python.org/dev/peps/pep-0484/ https://www.python.org/dev/peps/pep-0484/
""" """
def __init__(self, param1, param2, param3): def __init__(self, param1, param2, param3):
"""Example of docstring on the __init__ method. """Example of docstring on the __init__ method.
@ -240,11 +242,11 @@ class ExampleClass(object):
self.attr4 = ["attr4"] self.attr4 = ["attr4"]
self.attr5 = None self.attr5 = None
"""Optional[str]: Docstring *after* attribute, with type specified""" """Optional[str]: Docstring *after* attribute, with type specified."""
@property @property
def readonly_property(self): def readonly_property(self):
"""str: Properties should be documented in their getter method""" """str: Properties should be documented in their getter method."""
return "readonly_property" return "readonly_property"
@property @property