mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
[Napoleon] Updates docs to use single quoted strings & 4-space indentation
This commit is contained in:
Rob Ruana
parent
92bf7ca36a
commit
d5d6556a8a
@ -6,23 +6,23 @@ Style Guide`_. Docstrings may extend over multiple lines. Sections are created
|
||||
with a section header and a colon followed by a block of indented text.
|
||||
|
||||
Example:
|
||||
Examples can be given using either the ``Example`` or ``Examples``
|
||||
sections. Sections support any reStructuredText formatting, including
|
||||
literal blocks::
|
||||
Examples can be given using either the ``Example`` or ``Examples``
|
||||
sections. Sections support any reStructuredText formatting, including
|
||||
literal blocks::
|
||||
|
||||
$ python example_google.py
|
||||
$ python example_google.py
|
||||
|
||||
Section breaks are created by resuming unindented text. Section breaks
|
||||
are also implicitly created anytime a new section starts.
|
||||
|
||||
Attributes:
|
||||
module_level_variable1 (int): Module level variables may be documented in
|
||||
either the ``Attributes`` section of the module docstring, or in an
|
||||
inline docstring immediately following the variable.
|
||||
module_level_variable1 (int): Module level variables may be documented in
|
||||
either the ``Attributes`` section of the module docstring, or in an
|
||||
inline docstring immediately following the variable.
|
||||
|
||||
Either form is acceptable, but the two should not be mixed. Choose
|
||||
one convention to document module level variables and be consistent
|
||||
with it.
|
||||
Either form is acceptable, but the two should not be mixed. Choose
|
||||
one convention to document module level variables and be consistent
|
||||
with it.
|
||||
|
||||
.. _Google Python Style Guide:
|
||||
http://google.github.io/styleguide/pyguide.html
|
||||
@ -55,40 +55,40 @@ def module_level_function(param1, param2=None, *args, **kwargs):
|
||||
The format for a parameter is::
|
||||
|
||||
name (type): description
|
||||
The description may span multiple lines. Following
|
||||
lines should be indented. The "(type)" is optional.
|
||||
The description may span multiple lines. Following
|
||||
lines should be indented. The "(type)" is optional.
|
||||
|
||||
Multiple paragraphs are supported in parameter
|
||||
descriptions.
|
||||
Multiple paragraphs are supported in parameter
|
||||
descriptions.
|
||||
|
||||
Args:
|
||||
param1 (int): The first parameter.
|
||||
param2 (Optional[str]): The second parameter. Defaults to None.
|
||||
Second line of description should be indented.
|
||||
*args: Variable length argument list.
|
||||
**kwargs: Arbitrary keyword arguments.
|
||||
param1 (int): The first parameter.
|
||||
param2 (Optional[str]): The second parameter. Defaults to None.
|
||||
Second line of description should be indented.
|
||||
*args: Variable length argument list.
|
||||
**kwargs: Arbitrary keyword arguments.
|
||||
|
||||
Returns:
|
||||
bool: True if successful, False otherwise.
|
||||
bool: True if successful, False otherwise.
|
||||
|
||||
The return type is optional and may be specified at the beginning of
|
||||
the ``Returns`` section followed by a colon.
|
||||
The return type is optional and may be specified at the beginning of
|
||||
the ``Returns`` section followed by a colon.
|
||||
|
||||
The ``Returns`` section may span multiple lines and paragraphs.
|
||||
Following lines should be indented to match the first line.
|
||||
The ``Returns`` section may span multiple lines and paragraphs.
|
||||
Following lines should be indented to match the first line.
|
||||
|
||||
The ``Returns`` section supports any reStructuredText formatting,
|
||||
including literal blocks::
|
||||
The ``Returns`` section supports any reStructuredText formatting,
|
||||
including literal blocks::
|
||||
|
||||
{
|
||||
'param1': param1,
|
||||
'param2': param2
|
||||
}
|
||||
{
|
||||
'param1': param1,
|
||||
'param2': param2
|
||||
}
|
||||
|
||||
Raises:
|
||||
AttributeError: The ``Raises`` section is a list of all exceptions
|
||||
that are relevant to the interface.
|
||||
ValueError: If `param2` is equal to `param1`.
|
||||
AttributeError: The ``Raises`` section is a list of all exceptions
|
||||
that are relevant to the interface.
|
||||
ValueError: If `param2` is equal to `param1`.
|
||||
|
||||
|
||||
.. _PEP 484:
|
||||
@ -104,17 +104,17 @@ def example_generator(n):
|
||||
"""Generators have a ``Yields`` section instead of a ``Returns`` section.
|
||||
|
||||
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:
|
||||
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 should be written in doctest format, and should illustrate how
|
||||
to use the function.
|
||||
Examples should be written in doctest format, and should illustrate how
|
||||
to use the function.
|
||||
|
||||
>>> print [i for i in example_generator(4)]
|
||||
[0, 1, 2, 3]
|
||||
>>> print [i for i in example_generator(4)]
|
||||
[0, 1, 2, 3]
|
||||
|
||||
"""
|
||||
for i in range(n):
|
||||
@ -131,15 +131,15 @@ class ExampleError(Exception):
|
||||
convention to document the __init__ method and be consistent with it.
|
||||
|
||||
Note:
|
||||
Do not include the `self` parameter in the ``Args`` section.
|
||||
Do not include the `self` parameter in the ``Args`` section.
|
||||
|
||||
Args:
|
||||
msg (str): Human readable string describing the exception.
|
||||
code (Optional[int]): Error code.
|
||||
msg (str): Human readable string describing the exception.
|
||||
code (Optional[int]): Error code.
|
||||
|
||||
Attributes:
|
||||
msg (str): Human readable string describing the exception.
|
||||
code (int): Exception error code.
|
||||
msg (str): Human readable string describing the exception.
|
||||
code (int): Exception error code.
|
||||
|
||||
"""
|
||||
def __init__(self, msg, code):
|
||||
@ -162,8 +162,8 @@ class ExampleClass(object):
|
||||
to `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
|
||||
|
||||
Attributes:
|
||||
attr1 (str): Description of `attr1`.
|
||||
attr2 (Optional[int]): Description of `attr2`.
|
||||
attr1 (str): Description of `attr1`.
|
||||
attr2 (Optional[int]): Description of `attr2`.
|
||||
|
||||
|
||||
.. _PEP 484:
|
||||
@ -180,13 +180,13 @@ class ExampleClass(object):
|
||||
convention to document the __init__ method and be consistent with it.
|
||||
|
||||
Note:
|
||||
Do not include the `self` parameter in the ``Args`` section.
|
||||
Do not include the `self` parameter in the ``Args`` section.
|
||||
|
||||
Args:
|
||||
param1 (str): Description of `param1`.
|
||||
param2 (Optional[int]): Description of `param2`. Multiple
|
||||
lines are supported.
|
||||
param3 (List[str]): Description of `param3`.
|
||||
param1 (str): Description of `param1`.
|
||||
param2 (Optional[int]): Description of `param2`. Multiple
|
||||
lines are supported.
|
||||
param3 (List[str]): Description of `param3`.
|
||||
|
||||
"""
|
||||
self.attr1 = param1
|
||||
@ -194,7 +194,7 @@ class ExampleClass(object):
|
||||
self.attr3 = param3 #: Doc comment *inline* with attribute
|
||||
|
||||
#: List[str]: Doc comment *before* attribute, with type specified
|
||||
self.attr4 = ["attr4"]
|
||||
self.attr4 = ['attr4']
|
||||
|
||||
self.attr5 = None
|
||||
"""Optional[str]: Docstring *after* attribute, with type specified"""
|
||||
@ -202,7 +202,7 @@ class ExampleClass(object):
|
||||
@property
|
||||
def readonly_property(self):
|
||||
"""str: Properties should be documented in their getter method"""
|
||||
return "readonly_property"
|
||||
return 'readonly_property'
|
||||
|
||||
@property
|
||||
def readwrite_property(self):
|
||||
@ -212,7 +212,7 @@ class ExampleClass(object):
|
||||
If the setter method contains notable behavior, it should be
|
||||
mentioned here.
|
||||
"""
|
||||
return ["readwrite_property"]
|
||||
return ['readwrite_property']
|
||||
|
||||
@readwrite_property.setter
|
||||
def readwrite_property(self, value):
|
||||
@ -222,14 +222,14 @@ class ExampleClass(object):
|
||||
"""Class methods are similar to regular functions.
|
||||
|
||||
Note:
|
||||
Do not include the `self` parameter in the ``Args`` section.
|
||||
Do not include the `self` parameter in the ``Args`` section.
|
||||
|
||||
Args:
|
||||
param1: The first parameter.
|
||||
param2: The second parameter.
|
||||
param1: The first parameter.
|
||||
param2: The second parameter.
|
||||
|
||||
Returns:
|
||||
True if successful, False otherwise.
|
||||
True if successful, False otherwise.
|
||||
|
||||
"""
|
||||
return True
|
||||
|
||||
Loading…
Reference in New Issue
Block a user