diff options
Diffstat (limited to 'doc/ext/example_google.py')
| -rw-r--r-- | doc/ext/example_google.py | 197 |
1 files changed, 126 insertions, 71 deletions
diff --git a/doc/ext/example_google.py b/doc/ext/example_google.py index c94dcdf1d..81a312cfd 100644 --- a/doc/ext/example_google.py +++ b/doc/ext/example_google.py @@ -6,30 +6,41 @@ 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 simply resuming unindented text. Section breaks +Section breaks are created by resuming unindented text. Section breaks are also implicitly created anytime a new section starts. Attributes: - module_level_variable (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. + +Todo: + * For module TODOs + * You have to also use ``sphinx.ext.todo`` extension .. _Google Python Style Guide: - http://google-styleguide.googlecode.com/svn/trunk/pyguide.html + http://google.github.io/styleguide/pyguide.html """ -module_level_variable = 12345 +module_level_variable1 = 12345 + +module_level_variable2 = 98765 +"""int: Module level variable documented inline. + +The docstring may span multiple lines. The type may optionally be specified +on the first line, separated by a colon. +""" def module_level_function(param1, param2=None, *args, **kwargs): @@ -39,47 +50,53 @@ def module_level_function(param1, param2=None, *args, **kwargs): of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious. - If the parameter itself is optional, it should be noted by adding - ", optional" to the type. If \*args or \*\*kwargs are accepted, they - should be listed as \*args and \*\*kwargs. + Parameter types -- if given -- should be specified according to + `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced. + + If \*args or \*\*kwargs are accepted, + they should be listed as ``*args`` and ``**kwargs``. The format for a parameter is:: name (type): description - The description may span multiple lines. Following - lines should be indented. + 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 (str, optional): 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: + https://www.python.org/dev/peps/pep-0484/ """ if param1 == param2: @@ -91,17 +108,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): @@ -118,18 +135,19 @@ 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 (int, optional): Error code, defaults to 2. + 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=2): + + def __init__(self, msg, code): self.msg = msg self.code = code @@ -137,17 +155,28 @@ class ExampleError(Exception): class ExampleClass(object): """The summary line for a class docstring should fit on one line. - If the class has public attributes, they should be documented here + If the class has public attributes, they may be documented here in an ``Attributes`` section and follow the same formatting as a - function's ``Args`` section. + function's ``Args`` section. Alternatively, attributes may be documented + inline with the attribute's declaration (see __init__ method below). + + Properties created with the ``@property`` decorator should be documented + in the property's getter method. + + Attribute and property types -- if given -- should be specified according + to `PEP 484`_, though `PEP 484`_ conformance isn't required or enforced. Attributes: - attr1 (str): Description of `attr1`. - attr2 (list of str): Description of `attr2`. - attr3 (int): Description of `attr3`. + attr1 (str): Description of `attr1`. + attr2 (Optional[int]): Description of `attr2`. + + + .. _PEP 484: + https://www.python.org/dev/peps/pep-0484/ """ - def __init__(self, param1, param2, param3=0): + + def __init__(self, param1, param2, param3): """Example of docstring on the __init__ method. The __init__ method may be documented in either the class level @@ -157,46 +186,72 @@ 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 (list of str): Description of `param2`. Multiple - lines are supported. - param3 (int, optional): Description of `param3`, defaults to 0. + param1 (str): Description of `param1`. + param2 (Optional[int]): Description of `param2`. Multiple + lines are supported. + param3 (List[str]): Description of `param3`. """ self.attr1 = param1 self.attr2 = param2 - self.attr3 = param3 + self.attr3 = param3 #: Doc comment *inline* with attribute + + #: List[str]: Doc comment *before* attribute, with type specified + self.attr4 = ['attr4'] + + self.attr5 = None + """Optional[str]: Docstring *after* attribute, with type specified.""" + + @property + def readonly_property(self): + """str: Properties should be documented in their getter method.""" + return 'readonly_property' + + @property + def readwrite_property(self): + """List[str]: Properties with both a getter and setter should only + be documented in their getter method. + + If the setter method contains notable behavior, it should be + mentioned here. + """ + return ['readwrite_property'] + + @readwrite_property.setter + def readwrite_property(self, value): + value def example_method(self, param1, param2): """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 def __special__(self): - """By default special members with docstrings are included. + """By default special members with docstrings are not included. Special members are any methods or attributes that start with and end with a double underscore. Any special member with a docstring - will be included in the output. + will be included in the output, if + ``napoleon_include_special_with_doc`` is set to True. - This behavior can be disabled by changing the following setting in + This behavior can be enabled by changing the following setting in Sphinx's conf.py:: - napoleon_include_special_with_doc = False + napoleon_include_special_with_doc = True """ pass |