Docstrings might prolong over multiple traces. Sections are created with a bit header and a colon adopted by a block of indented text. Example: Examples could be given utilizing either the “Example“ or “Examples“ sections. Section breaks are created by resuming unindented textual content. Section breaks are additionally implicitly created anytime a new part starts. 1 (int): Module stage variables may be documented in both the “Attributes“ part of the module docstring, or in an inline docstring immediately following the variable. Either type is acceptable, however the 2 should not be mixed. Choose one convention to document module degree variables and be per it. You need to also use “sphinx.ext.todo“ extension .. Module stage variable documented inline. The docstring could span a number of traces. The type could optionally be specified on the primary line, separated by a colon. Example operate with varieties documented within the docstring. Args: param1 (int): The first parameter. 2 (str): The second parameter. Returns: bool: The return value.
True for achievement, False in any other case. Example perform with PEP 484 sort annotations. Args: param1: The first parameter. 2: The second parameter. Returns: The return value. True for fulfillment, False in any other case. This is an instance of a module degree operate. Function parameters needs to be documented within the “Args“ part. The identify of every parameter is required. The kind and description of each parameter is optionally available, but ought to be included if not apparent. The format for a parameter is:: name (type): description The outline may span multiple lines. Following strains must be indented. The “(kind)” is optional. Multiple paragraphs are supported in parameter descriptions. Args: param1 (int): The first parameter. 2 (:obj:`str`, non-compulsory): The second parameter. Defaults to None. Second line of description should be indented. Variable size argument list. Arbitrary keyword arguments. Returns: bool: True if successful, False otherwise. The return sort is optionally available and may be specified initially of the “Returns“ section adopted by a colon. The “Returns“ part might span multiple strains and paragraphs.
Following lines must be indented to match the primary line. Raises: AttributeError: The “Raises“ part is an inventory of all exceptions which can be related to the interface. ValueError: If `param2` is equal to `param1`. Generators have a “Yields“ section instead of a “Returns“ part. Args: n (int): The upper limit of the vary to generate, from 0 to `n` – 1. Yields: int: The next quantity in the range of zero to `n` – 1. Examples: Examples should be written in doctest format, and should illustrate how to make use of the perform. Exceptions are documented in the same manner as classes. Either type is acceptable, but the 2 should not be combined. Note: Do not embody the `self` parameter within the “Args“ section. Args: msg (str): Human readable string describing the exception. Error code. Attributes: msg (str): Human readable string describing the exception. The summary line for a category docstring should match on one line. If the category has public attributes, they could also be documented right here in an “Attributes“ part and follow the identical formatting as a perform’s “Args“ section.
Properties created with the “@property“ decorator needs to be documented in the property’s getter method. Attributes: attr1 (str): Description of `attr1`. 2 (:obj:`int`, optional): Description of `attr2`. Either form is acceptable, however the two should not be mixed. Note: Don’t include the `self` parameter within the “Args“ part. Args: param1 (str): Description of `param1`. 2 (:obj:`int`, non-compulsory): Description of `param2`. Multiple traces are supported. Three (:obj:`list` of :obj:`str`): Description of `param3`. Properties with each a getter and setter should solely be documented in their getter technique. If the setter technique incorporates notable habits, it must be mentioned right here. Class strategies are similar to common functions. Note: Don’t embrace the `self` parameter within the “Args“ part. Args: param1: The first parameter. 2: The second parameter. Returns: True if successful, False otherwise. By default special members with docstrings should not included. Special members are any methods or attributes that start with and end with a double underscore. By default personal members are usually not included. By default they aren’t included within the output.