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] Updates docs to use single quoted strings & 4-space indentation

Browse Source
This commit is contained in:
Rob Ruana 2015-06-11 20:21:37 -07:00
parent 92bf7ca36a
commit d5d6556a8a
1 changed files with 58 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
doc/ext/example_google.py
View File

@ -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. with a section header and a colon followed by a block of indented text.
Example: Example:
Examples can be given using either the ``Example`` or ``Examples`` Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including sections. Sections support any reStructuredText formatting, including
literal blocks:: literal blocks::
$ python example_google.py $ python example_google.py
Section breaks are created by resuming unindented text. Section breaks Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts. are also implicitly created anytime a new section starts.
Attributes: Attributes:
module_level_variable1 (int): Module level variables may be documented in module_level_variable1 (int): Module level variables may be documented in
either the ``Attributes`` section of the module docstring, or in an either the ``Attributes`` section of the module docstring, or in an
inline docstring immediately following the variable. inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent one convention to document module level variables and be consistent
with it. with it.
.. _Google Python Style Guide: .. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html 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:: The format for a parameter is::
name (type): description name (type): description
The description may span multiple lines. Following The description may span multiple lines. Following
lines should be indented. The "(type)" is optional. lines should be indented. The "(type)" is optional.
Multiple paragraphs are supported in parameter Multiple paragraphs are supported in parameter
descriptions. descriptions.
Args: Args:
param1 (int): The first parameter. param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None. param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented. Second line of description should be indented.
*args: Variable length argument list. *args: Variable length argument list.
**kwargs: Arbitrary keyword arguments. **kwargs: Arbitrary keyword arguments.
Returns: 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 return type is optional and may be specified at the beginning of
the ``Returns`` section followed by a colon. the ``Returns`` section followed by a colon.
The ``Returns`` section may span multiple lines and paragraphs. The ``Returns`` section may span multiple lines and paragraphs.
Following lines should be indented to match the first line. Following lines should be indented to match the first line.
The ``Returns`` section supports any reStructuredText formatting, The ``Returns`` section supports any reStructuredText formatting,
including literal blocks:: including literal blocks::
{ {
'param1': param1, 'param1': param1,
'param2': param2 'param2': param2
} }
Raises: Raises:
AttributeError: The ``Raises`` section is a list of all exceptions AttributeError: The ``Raises`` section is a list of all exceptions
that are relevant to the interface. that are relevant to the interface.
ValueError: If `param2` is equal to `param1`. ValueError: If `param2` is equal to `param1`.
.. _PEP 484: .. _PEP 484:
@ -104,17 +104,17 @@ 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]
""" """
for i in range(n): for i in range(n):
@ -131,15 +131,15 @@ class ExampleError(Exception):
convention to document the __init__ method and be consistent with it. convention to document the __init__ method and be consistent with it.
Note: Note:
Do not include the `self` parameter in the ``Args`` section. Do not include the `self` parameter in the ``Args`` section.
Args: Args:
msg (str): Human readable string describing the exception. msg (str): Human readable string describing the exception.
code (Optional[int]): Error code. code (Optional[int]): Error code.
Attributes: Attributes:
msg (str): Human readable string describing the exception. msg (str): Human readable string describing the exception.
code (int): Exception error code. code (int): Exception error code.
""" """
def __init__(self, msg, 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. to `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced.
Attributes: Attributes:
attr1 (str): Description of `attr1`. attr1 (str): Description of `attr1`.
attr2 (Optional[int]): Description of `attr2`. attr2 (Optional[int]): Description of `attr2`.
.. _PEP 484: .. _PEP 484:
@ -180,13 +180,13 @@ class ExampleClass(object):
convention to document the __init__ method and be consistent with it. convention to document the __init__ method and be consistent with it.
Note: Note:
Do not include the `self` parameter in the ``Args`` section. Do not include the `self` parameter in the ``Args`` section.
Args: Args:
param1 (str): Description of `param1`. param1 (str): Description of `param1`.
param2 (Optional[int]): Description of `param2`. Multiple param2 (Optional[int]): Description of `param2`. Multiple
lines are supported. lines are supported.
param3 (List[str]): Description of `param3`. param3 (List[str]): Description of `param3`.
""" """
self.attr1 = param1 self.attr1 = param1
@ -194,7 +194,7 @@ class ExampleClass(object):
self.attr3 = param3 #: Doc comment *inline* with attribute self.attr3 = param3 #: Doc comment *inline* with attribute
#: List[str]: Doc comment *before* attribute, with type specified #: List[str]: Doc comment *before* attribute, with type specified
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"""
@ -202,7 +202,7 @@ class ExampleClass(object):
@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
def readwrite_property(self): def readwrite_property(self):
@ -212,7 +212,7 @@ class ExampleClass(object):
If the setter method contains notable behavior, it should be If the setter method contains notable behavior, it should be
mentioned here. mentioned here.
""" """
return ["readwrite_property"] return ['readwrite_property']
@readwrite_property.setter @readwrite_property.setter
def readwrite_property(self, value): def readwrite_property(self, value):
@ -222,14 +222,14 @@ class ExampleClass(object):
"""Class methods are similar to regular functions. """Class methods are similar to regular functions.
Note: Note:
Do not include the `self` parameter in the ``Args`` section. Do not include the `self` parameter in the ``Args`` section.
Args: Args:
param1: The first parameter. param1: The first parameter.
param2: The second parameter. param2: The second parameter.
Returns: Returns:
True if successful, False otherwise. True if successful, False otherwise.
""" """
return True return True