diff options
Diffstat (limited to 'doc/ext')
| -rw-r--r-- | doc/ext/builtins.rst | 24 | ||||
| -rw-r--r-- | doc/ext/doctest.rst | 23 | ||||
| -rw-r--r-- | doc/ext/example_google.py | 65 | ||||
| -rw-r--r-- | doc/ext/example_numpy.py | 79 | ||||
| -rw-r--r-- | doc/ext/graphviz.rst | 4 | ||||
| -rw-r--r-- | doc/ext/inheritance.rst | 5 | ||||
| -rw-r--r-- | doc/ext/intersphinx.rst | 11 | ||||
| -rw-r--r-- | doc/ext/napoleon.rst | 85 | ||||
| -rw-r--r-- | doc/ext/thirdparty.rst | 35 | ||||
| -rw-r--r-- | doc/ext/todo.rst | 15 | ||||
| -rw-r--r-- | doc/ext/viewcode.rst | 28 |
11 files changed, 321 insertions, 53 deletions
diff --git a/doc/ext/builtins.rst b/doc/ext/builtins.rst new file mode 100644 index 000000000..6d5e59a89 --- /dev/null +++ b/doc/ext/builtins.rst @@ -0,0 +1,24 @@ +Builtin Sphinx extensions +------------------------- + +These extensions are built in and can be activated by respective entries in the +:confval:`extensions` configuration value: + +.. toctree:: + + autodoc + autosectionlabel + autosummary + coverage + doctest + extlinks + githubpages + graphviz + ifconfig + inheritance + intersphinx + linkcode + math + napoleon + todo + viewcode diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 2d06b69e6..818b86007 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -59,12 +59,9 @@ a comma-separated list of group names. .. rst:directive:: .. doctest:: [group] A doctest-style code block. You can use standard :mod:`doctest` flags for - controlling how actual output is compared with what you give as output. By - default, these options are enabled: ``ELLIPSIS`` (allowing you to put - ellipses in the expected output that match anything in the actual output), - ``IGNORE_EXCEPTION_DETAIL`` (not comparing tracebacks), - ``DONT_ACCEPT_TRUE_FOR_1`` (by default, doctest accepts "True" in the output - where "1" is given -- this is a relic of pre-Python 2.2 times). + controlling how actual output is compared with what you give as output. The + default set of flags is specified by the :confval:`doctest_default_flags` + configuration variable. This directive supports two options: @@ -182,6 +179,20 @@ Configuration The doctest extension uses the following configuration values: +.. confval:: doctest_default_flags + + By default, these options are enabled: + + - ``ELLIPSIS``, allowing you to put ellipses in the expected output that + match anything in the actual output; + - ``IGNORE_EXCEPTION_DETAIL``, causing everything following the leftmost + colon and any module information in the exception name to be ignored; + - ``DONT_ACCEPT_TRUE_FOR_1``, rejecting "True" in the output where "1" is + given -- the default behavior of accepting this substitution is a relic of + pre-Python 2.2 times. + + .. versionadded:: 1.5 + .. confval:: doctest_path A list of directories that will be added to :data:`sys.path` when the doctest diff --git a/doc/ext/example_google.py b/doc/ext/example_google.py index 81a312cfd..34a720e36 100644 --- a/doc/ext/example_google.py +++ b/doc/ext/example_google.py @@ -43,6 +43,39 @@ on the first line, separated by a colon. """ +def function_with_types_in_docstring(param1, param2): + """Example function with types documented in the docstring. + + `PEP 484`_ type annotations are supported. If attribute, parameter, and + return types are annotated according to `PEP 484`_, they do not need to be + included in the docstring: + + Args: + param1 (int): The first parameter. + param2 (str): The second parameter. + + Returns: + bool: The return value. True for success, False otherwise. + + .. _PEP 484: + https://www.python.org/dev/peps/pep-0484/ + + """ + + +def function_with_pep484_type_annotations(param1: int, param2: str) -> bool: + """Example function with PEP 484 type annotations. + + Args: + param1: The first parameter. + param2: The second parameter. + + Returns: + The return value. True for success, False otherwise. + + """ + + def module_level_function(param1, param2=None, *args, **kwargs): """This is an example of a module level function. @@ -50,9 +83,6 @@ 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. - 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``. @@ -67,7 +97,7 @@ def module_level_function(param1, param2=None, *args, **kwargs): Args: param1 (int): The first parameter. - param2 (Optional[str]): The second parameter. Defaults to None. + param2 (:obj:`str`, optional): The second parameter. Defaults to None. Second line of description should be indented. *args: Variable length argument list. **kwargs: Arbitrary keyword arguments. @@ -94,10 +124,6 @@ def module_level_function(param1, param2=None, *args, **kwargs): 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: raise ValueError('param1 may not be equal to param2') @@ -139,7 +165,7 @@ class ExampleError(Exception): Args: msg (str): Human readable string describing the exception. - code (Optional[int]): Error code. + code (:obj:`int`, optional): Error code. Attributes: msg (str): Human readable string describing the exception. @@ -163,16 +189,9 @@ class ExampleClass(object): 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 (Optional[int]): Description of `attr2`. - - - .. _PEP 484: - https://www.python.org/dev/peps/pep-0484/ + attr2 (:obj:`int`, optional): Description of `attr2`. """ @@ -190,20 +209,20 @@ class ExampleClass(object): Args: param1 (str): Description of `param1`. - param2 (Optional[int]): Description of `param2`. Multiple + param2 (:obj:`int`, optional): Description of `param2`. Multiple lines are supported. - param3 (List[str]): Description of `param3`. + param3 (list(str)): Description of `param3`. """ self.attr1 = param1 self.attr2 = param2 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.attr5 = None - """Optional[str]: Docstring *after* attribute, with type specified.""" + """str: Docstring *after* attribute, with type specified.""" @property def readonly_property(self): @@ -212,8 +231,8 @@ class ExampleClass(object): @property def readwrite_property(self): - """List[str]: Properties with both a getter and setter should only - be documented in their getter method. + """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. diff --git a/doc/ext/example_numpy.py b/doc/ext/example_numpy.py index bb91cac82..7a2db94cc 100644 --- a/doc/ext/example_numpy.py +++ b/doc/ext/example_numpy.py @@ -37,6 +37,7 @@ module_level_variable1 : int one convention to document module level variables and be consistent with it. + .. _NumPy Documentation HOWTO: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt @@ -52,6 +53,52 @@ on the first line, separated by a colon. """ +def function_with_types_in_docstring(param1, param2): + """Example function with types documented in the docstring. + + `PEP 484`_ type annotations are supported. If attribute, parameter, and + return types are annotated according to `PEP 484`_, they do not need to be + included in the docstring: + + Parameters + ---------- + param1 : int + The first parameter. + param2 : str + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + + .. _PEP 484: + https://www.python.org/dev/peps/pep-0484/ + + """ + + +def function_with_pep484_type_annotations(param1: int, param2: str) -> bool: + """Example function with PEP 484 type annotations. + + The return type must be duplicated in the docstring to comply + with the NumPy docstring style. + + Parameters + ---------- + param1 + The first parameter. + param2 + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + + """ + + def module_level_function(param1, param2=None, *args, **kwargs): """This is an example of a module level function. @@ -59,9 +106,6 @@ def module_level_function(param1, param2=None, *args, **kwargs): The name of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious. - 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``. @@ -81,7 +125,7 @@ def module_level_function(param1, param2=None, *args, **kwargs): ---------- param1 : int The first parameter. - param2 : Optional[str] + param2 : :obj:`str`, optional The second parameter. *args Variable length argument list. @@ -113,10 +157,6 @@ def module_level_function(param1, param2=None, *args, **kwargs): ValueError If `param2` is equal to `param1`. - - .. _PEP 484: - https://www.python.org/dev/peps/pep-0484/ - """ if param1 == param2: raise ValueError('param1 may not be equal to param2') @@ -166,7 +206,7 @@ class ExampleError(Exception): ---------- msg : str Human readable string describing the exception. - code : Optional[int] + code : :obj:`int`, optional Numeric error code. Attributes @@ -194,20 +234,13 @@ class ExampleClass(object): 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 : Optional[int] + attr2 : :obj:`int`, optional Description of `attr2`. - - .. _PEP 484: - https://www.python.org/dev/peps/pep-0484/ - """ def __init__(self, param1, param2, param3): @@ -227,10 +260,10 @@ class ExampleClass(object): ---------- param1 : str Description of `param1`. - param2 : List[str] + param2 : list(str) Description of `param2`. Multiple lines are supported. - param3 : Optional[int] + param3 : :obj:`int`, optional Description of `param3`. """ @@ -238,11 +271,11 @@ class ExampleClass(object): self.attr2 = param2 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.attr5 = None - """Optional[str]: Docstring *after* attribute, with type specified.""" + """str: Docstring *after* attribute, with type specified.""" @property def readonly_property(self): @@ -251,8 +284,8 @@ class ExampleClass(object): @property def readwrite_property(self): - """List[str]: Properties with both a getter and setter should only - be documented in their getter method. + """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. diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst index ca34fa281..0994c932a 100644 --- a/doc/ext/graphviz.rst +++ b/doc/ext/graphviz.rst @@ -96,6 +96,10 @@ It adds these directives: All three directives support a ``graphviz_dot`` option that can be switch the ``dot`` command within the directive. +.. versionadded:: 1.5 + All three directives support a ``align`` option to align the graph horizontal. + The values "left", "center", "right" are allowed. + There are also these new config values: .. confval:: graphviz_dot diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst index 5e0a76fcc..bd287aa49 100644 --- a/doc/ext/inheritance.rst +++ b/doc/ext/inheritance.rst @@ -33,10 +33,15 @@ It adds this directive: It also supports a ``private-bases`` flag option; if given, private base classes (those whose name starts with ``_``) will be included. + You can use ``caption`` option to give a caption to the diagram. + .. versionchanged:: 1.1 Added ``private-bases`` option; previously, all bases were always included. + .. versionchanged:: 1.5 + Added ``caption`` option + New config values are: diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst index 785164a0c..fb0114fc4 100644 --- a/doc/ext/intersphinx.rst +++ b/doc/ext/intersphinx.rst @@ -121,3 +121,14 @@ linking: The maximum number of days to cache remote inventories. The default is ``5``, meaning five days. Set this to a negative value to cache inventories for unlimited time. + +.. confval:: intersphinx_timeout + + The number of seconds for timeout. The default is ``None``, meaning do not + timeout. + + .. note:: + + timeout is not a time limit on the entire response download; rather, an + exception is raised if the server has not issued a response for timeout + seconds. diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst index 304d8ac22..ea3e4042f 100644 --- a/doc/ext/napoleon.rst +++ b/doc/ext/napoleon.rst @@ -186,11 +186,60 @@ not be mixed. Choose one style for your project and be consistent with it. * :ref:`example_google` * :ref:`example_numpy` - For Python type annotations, see `PEP 484`_. + +Type Annotations +---------------- + +`PEP 484`_ introduced a standard way to express types in Python code. +This is an alternative to expressing types directly in docstrings. +One benefit of expressing types according to `PEP 484`_ is that +type checkers and IDEs can take advantage of them for static code +analysis. + +Google style with Python 3 type annotations:: + + def func(arg1: int, arg2: str) -> bool: + """Summary line. + + Extended description of function. + + Args: + arg1: Description of arg1 + arg2: Description of arg2 + + Returns: + Description of return value + + """ + return True + +Google style with types in docstrings:: + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True + +.. Note:: + `Python 2/3 compatible annotations`_ aren't currently + supported by Sphinx and won't show up in the docs. .. _PEP 484: https://www.python.org/dev/peps/pep-0484/ +.. _Python 2/3 compatible annotations: + https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code + Configuration ============= @@ -208,6 +257,7 @@ enabled in `conf.py`:: # Napoleon settings napoleon_google_docstring = True napoleon_numpy_docstring = True + napoleon_include_init_with_doc = False napoleon_include_private_with_doc = False napoleon_include_special_with_doc = True napoleon_use_admonition_for_examples = False @@ -234,6 +284,23 @@ enabled in `conf.py`:: True to parse `NumPy style`_ docstrings. False to disable support for NumPy style docstrings. *Defaults to True.* +.. confval:: napoleon_include_init_with_doc + + True to list ``__init___`` docstrings separately from the class + docstring. False to fall back to Sphinx's default behavior, which + considers the ``__init___`` docstring as part of the class + documentation. *Defaults to False.* + + **If True**:: + + def __init__(self): + \"\"\" + This will be included in the docs because it has a docstring + \"\"\" + + def __init__(self): + # This will NOT be included in the docs + .. confval:: napoleon_include_private_with_doc True to include private members (like ``_membername``) with docstrings @@ -371,6 +438,22 @@ enabled in `conf.py`:: * **arg2** (*int, optional*) -- Description of `arg2`, defaults to 0 +.. confval:: napoleon_use_keyword + + True to use a ``:keyword:`` role for each function keyword argument. + False to use a single ``:keyword arguments:`` role for all the + keywords. + *Defaults to True.* + + This behaves similarly to :attr:`napoleon_use_param`. Note unlike docutils, + ``:keyword:`` and ``:param:`` will not be treated the same way - there will + be a separate "Keyword Arguments" section, rendered in the same fashion as + "Parameters" section (type links created if possible) + + .. seealso:: + + :attr:`napoleon_use_param` + .. confval:: napoleon_use_rtype True to use the ``:rtype:`` role for the return type. False to output diff --git a/doc/ext/thirdparty.rst b/doc/ext/thirdparty.rst new file mode 100644 index 000000000..6304e4af3 --- /dev/null +++ b/doc/ext/thirdparty.rst @@ -0,0 +1,35 @@ +Third-party extensions +---------------------- + +You can find several extensions contributed by users in the `Sphinx Contrib`_ +repository. It is open for anyone who wants to maintain an extension +publicly; just send a short message asking for write permissions. + +There are also several extensions hosted elsewhere. The `Sphinx extension +survey <http://sphinxext-survey.readthedocs.org/en/latest/>`__ contains a +comprehensive list. + +If you write an extension that you think others will find useful or you think +should be included as a part of Sphinx, please write to the project mailing +list (`join here <https://groups.google.com/forum/#!forum/sphinx-dev>`_). + +.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib + + +Where to put your own extensions? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Extensions local to a project should be put within the project's directory +structure. Set Python's module search path, ``sys.path``, accordingly so that +Sphinx can find them. +E.g., if your extension ``foo.py`` lies in the ``exts`` subdirectory of the +project root, put into :file:`conf.py`:: + + import sys, os + + sys.path.append(os.path.abspath('exts')) + + extensions = ['foo'] + +You can also install extensions anywhere else on ``sys.path``, e.g. in the +``site-packages`` directory. diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst index a809bc665..09abfa9b8 100644 --- a/doc/ext/todo.rst +++ b/doc/ext/todo.rst @@ -34,6 +34,13 @@ There is also an additional config value: If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output, else they produce nothing. The default is ``False``. +.. confval:: todo_emit_warnings + + If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries. + The default is ``False``. + + .. versionadded:: 1.5 + .. confval:: todo_link_only If this is ``True``, :rst:dir:`todolist` produce output without file path and line, @@ -41,3 +48,11 @@ There is also an additional config value: .. versionadded:: 1.4 +autodoc provides the following an additional event: + +.. event:: todo-defined (app, node) + + .. versionadded:: 1.5 + + Emitted when a todo is defined. *node* is the defined ``sphinx.ext.todo.todo_node`` + node. diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst index 5bf8eb033..5823090f6 100644 --- a/doc/ext/viewcode.rst +++ b/doc/ext/viewcode.rst @@ -15,6 +15,11 @@ a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back from the source to the description will also be inserted. +This extension works only on HTML related builders like ``html``, +``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except +``singlehtml``. By default ``epub`` builder doesn't +support this extension (see :confval:`viewcode_enable_epub`). + There is an additional config value: .. confval:: viewcode_import @@ -34,3 +39,26 @@ There is an additional config value: main routine is protected by a ``if __name__ == '__main__'`` condition. .. versionadded:: 1.3 + +.. confval:: viewcode_enable_epub + + If this is ``True``, viewcode extension is also enabled even if you use + epub builders. This extension generates pages outside toctree, but this + is not preferred as epub format. + + Until 1.4.x, this extension is always enabled. If you want to generate + epub as same as 1.4.x, you should set ``True``, but epub format checker's + score becomes worse. + + The default is ``False``. + + .. versionadded:: 1.5 + + .. warning:: + + Not all epub readers support pages generated by viewcode extension. + These readers ignore links to pages are not under toctree. + + Some reader's rendering result are corrupted and + `epubcheck <https://github.com/IDPF/epubcheck>`_'s score + becomes worse even if the reader supports. |