Merge branch '3.x' into 6040_autosummary_recursive

doc/usage/extensions/autodoc.rst

@@ -140,6 +140,20 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
      .. versionadded:: 1.1
 
+   * autodoc considers a member private if its docstring contains
+     ``:meta private:`` in its :ref:`info-field-lists`.
+     For example:
+
+     .. code-block:: rst
+
+        def my_function(my_arg, my_other_arg):
+            """blah blah blah
+
+            :meta private:
+            """
+
+     .. versionadded:: 3.0
+
    * Python "special" members (that is, those named like ``__special__``) will
      be included if the ``special-members`` flag option is given::
 
@@ -157,7 +171,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
    * For classes and exceptions, members inherited from base classes will be
      left out when documenting all members, unless you give the
-     ``inherited-members`` flag option, in addition to ``members``::
+     ``inherited-members`` option, in addition to ``members``::
 
         .. autoclass:: Noodle
            :members:
@@ -166,11 +180,29 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      This can be combined with ``undoc-members`` to document *all* available
      members of the class or module.
 
+     It can take an ancestor class not to document inherited members from it.
+     By default, members of ``object`` class are not documented.  To show them
+     all, give ``None`` to the option.
+
+     For example; If your class ``Foo`` is derived from ``list`` class and
+     you don't want to document ``list.__len__()``, you should specify a
+     option ``:inherited-members: list`` to avoid special members of list
+     class.
+
+     Another example; If your class Foo has ``__str__`` special method and
+     autodoc directive has both ``inherited-members`` and ``special-members``,
+     ``__str__`` will be documented as in the past, but other special method
+     that are not implemented in your class ``Foo``.
+
      Note: this will lead to markup errors if the inherited members come from a
      module whose docstrings are not reST formatted.
 
      .. versionadded:: 0.3
 
+     .. versionchanged:: 3.0
+
+        It takes an anchestor class name as an argument.
+
    * It's possible to override the signature for explicitly documented callable
      objects (functions, methods, classes) with the regular syntax that will
      override the signature gained from introspection::
@@ -308,9 +340,6 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
       a decorator replaces the decorated function with another, it must copy the
       original ``__doc__`` to the new function.
 
-      From Python 2.5, :func:`functools.wraps` can be used to create
-      well-behaved decorating functions.
-
 
 Configuration
 -------------
@@ -437,9 +466,13 @@ There are also config values that you can set:
    following values:
 
    * ``'signature'`` -- Show typehints as its signature (default)
+   * ``'description'`` -- Show typehints as content of function or method
    * ``'none'`` -- Do not show typehints
 
-   .. versionadded: 2.1
+   .. versionadded:: 2.1
+   .. versionadded:: 3.0
+
+      New option ``'description'`` is added.
 
 .. confval:: autodoc_warningiserror
 
@@ -494,6 +527,17 @@ autodoc provides the following additional events:
       auto directive
    :param lines: the lines of the docstring, see above
 
+.. event:: autodoc-before-process-signature (app, obj, bound_method)
+
+   .. versionadded:: 2.4
+
+   Emitted before autodoc formats a signature for an object. The event handler
+   can modify an object to change its signature.
+
+   :param app: the Sphinx application object
+   :param obj: the object itself
+   :param bound_method: a boolean indicates an object is bound method or not
+
 .. event:: autodoc-process-signature (app, what, name, obj, options, signature, return_annotation)
 
    .. versionadded:: 0.5

doc/usage/extensions/autosummary.rst

@@ -81,6 +81,12 @@ The :mod:`sphinx.ext.autosummary` extension does this in three parts:
      directory. If no argument is given, output is placed in the same directory
      as the file that contains the directive.
 
+     You can also use ``caption`` option to give a caption to the toctree.
+
+     .. versionadded:: 3.1
+
+        caption option added.
+
    * If you don't want the :rst:dir:`autosummary` to show function signatures in
      the listing, include the ``nosignatures`` option::
 
@@ -162,6 +168,11 @@ also use these config values:
    The new files will be placed in the directories specified in the
    ``:toctree:`` options of the directives.
 
+   .. versionchanged:: 2.3
+
+      Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc`
+      does.
+
 .. confval:: autosummary_generate_overwrite
 
    If true, autosummary already overwrites stub files by generated contents.
@@ -300,6 +311,7 @@ Additionally, the following filters are available
    replaces the builtin Jinja `escape filter`_ that does html-escaping.
 
 .. function:: underline(s, line='=')
+   :noindex:
 
    Add a title underline to a piece of text.
 

doc/usage/extensions/doctest.rst

@@ -11,11 +11,15 @@
            pair: testing; snippets
 
 
-This extension allows you to test snippets in the documentation in a natural
-way.  It works by collecting specially-marked up code blocks and running them as
-doctest tests.
+It is often helpful to include snippets of code in your documentation and
+demonstrate the results of executing them. But it is important to ensure that
+the documentation stays up-to-date with the code.
 
-Within one document, test code is partitioned in *groups*, where each group
+This extension allows you to test such code snippets in the documentation in
+a natural way.  If you mark the code blocks as shown here, the ``doctest``
+builder will collect them and run them as doctest tests.
+
+Within each document, you can assign each snippet to a *group*. Each group
 consists of:
 
 * zero or more *setup code* blocks (e.g. importing the module to test)

doc/usage/extensions/duration.rst

@@ -0,0 +1,11 @@
+:mod:`sphinx.ext.duration` -- Measure durations of Sphinx processing
+====================================================================
+
+.. module:: sphinx.ext.duration
+   :synopsis: Measure durations of Sphinx processing
+
+.. versionadded:: 2.4
+
+This extension measures durations of Sphinx processing and show its
+result at end of the build.  It is useful for inspecting what document
+is slowly built.

doc/usage/extensions/graphviz.rst

@@ -82,6 +82,13 @@ It adds these directives:
 
       .. versionadded:: 1.6
 
+   .. rst:directive:option:: class: class names
+      :type: a list of class names separeted by spaces
+
+      The class name of the graph.
+
+      .. versionadded:: 2.4
+
 
 .. rst:directive:: graph
 
@@ -131,6 +138,13 @@ It adds these directives:
 
       .. versionadded:: 1.6
 
+   .. rst:directive:option:: class: class names
+      :type: a list of class names separeted by spaces
+
+      The class name of the graph.
+
+      .. versionadded:: 2.4
+
 
 .. rst:directive:: digraph
 
@@ -176,6 +190,13 @@ It adds these directives:
 
       .. versionadded:: 1.6
 
+   .. rst:directive:option:: class: class names
+      :type: a list of class names separeted by spaces
+
+      The class name of the graph.
+
+      .. versionadded:: 2.4
+
 
 There are also these config values:
 

doc/usage/extensions/imgconverter.rst

@@ -34,7 +34,19 @@ Configuration
    A path to :command:`convert` command.  By default, the imgconverter uses
    the command from search paths.
 
+   On windows platform, :command:`magick` command is used by default.
+
+   .. versionchanged:: 3.1
+
+      Use :command:`magick` command by default on windows
+
 .. confval:: image_converter_args
 
    Additional command-line arguments to give to :command:`convert`, as a list.
    The default is an empty list ``[]``.
+
+   On windows platform, it defaults to ``["convert"]``.
+
+   .. versionchanged:: 3.1
+
+      Use ``["convert"]`` by default on windows

doc/usage/extensions/index.rst

@@ -23,6 +23,7 @@ These extensions are built in and can be activated by respective entries in the
    autosummary
    coverage
    doctest
+   duration
    extlinks
    githubpages
    graphviz

doc/usage/extensions/intersphinx.rst

@@ -148,3 +148,13 @@ project. The following example prints the Intersphinx mapping of the Python 3
 documentation::
 
    $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+
+Using Intersphinx with inventory file under Basic Authorization
+---------------------------------------------------------------
+
+Intersphinx supports Basic Authorization like this::
+
+      intersphinx_mapping = {'python': ('https://user:password@docs.python.org/3',
+                                        None)}
+
+The user and password will be stripped from the URL when generating the links.

doc/usage/extensions/math.rst

@@ -50,7 +50,7 @@ are built:
    ``preview-latex-style`` on Ubuntu xenial).  Therefore, the default for this
    option is ``False`` but it is strongly recommended to set it to ``True``.
 
-   .. versionchanged:: 2.1
+   .. versionchanged:: 2.2
 
       This option can be used with the ``'svg'`` :confval:`imgmath_image_format`.
 
@@ -80,6 +80,14 @@ are built:
    This value should only contain the path to the latex executable, not further
    arguments; use :confval:`imgmath_latex_args` for that purpose.
 
+   .. hint::
+
+      Some fancy LaTeX mark-up (an example was reported which used TikZ to add
+      various decorations to the equation) require multiple runs of the LaTeX
+      executable.  To handle this, set this configuration setting to
+      ``'latexmk'`` (or a full path to it) as this Perl script reliably
+      chooses dynamically how many latex runs are needed.
+
 .. confval:: imgmath_latex_args
 
    Additional arguments to give to latex, as a list.  The default is an empty
@@ -183,6 +191,8 @@ Sphinx but is set to automatically include it from a third-party site.
 
    The default is empty (``{}``).
 
+   .. versionadded:: 1.8
+
 .. confval:: mathjax_config
 
    The inline configuration options for mathjax.  The value is used as a
@@ -198,6 +208,8 @@ Sphinx but is set to automatically include it from a third-party site.
 
    The default is empty (not configured).
 
+   .. versionadded:: 1.8
+
 .. _Using in-line configuration options: https://docs.mathjax.org/en/latest/configuration.html#using-in-line-configuration-options
 
 :mod:`sphinx.ext.jsmath` -- Render math via JavaScript

doc/usage/extensions/napoleon.rst

@@ -56,7 +56,7 @@ source code files.
 .. _Google:
    https://google.github.io/styleguide/pyguide.html#Comments
 .. _NumPy:
-   https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+   https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
 .. _Khan Academy:
    https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings