Merge branch '3.x'

doc/conf.py

@@ -110,7 +110,10 @@ texinfo_documents = [
      1),
 ]
 
-intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'requests': ('https://requests.readthedocs.io/en/master', None),
+}
 
 # Sphinx document translation with sphinx gettext feature uses these settings:
 locale_dirs = ['locale/']

doc/extdev/deprecated.rst

@@ -61,6 +61,12 @@ The following is a list of deprecated interfaces.
      - 5.0
      - N/A
 
+   * - The ``no_docstring`` argument of
+       ``sphinx.ext.autodoc.Documenter.add_content()``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.Documenter.get_doc()``
+
    * - ``sphinx.ext.autodoc.Documenter.get_object_members()``
      - 3.4
      - 6.0
@@ -71,6 +77,21 @@ The following is a list of deprecated interfaces.
      - 5.0
      - ``sphinx.ext.autodoc.DataDocumenter``
 
+   * - ``sphinx.ext.autodoc.GenericAliasDocumenter``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.DataDocumenter``
+
+   * - ``sphinx.ext.autodoc.InstanceAttributeDocumenter``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.AttributeDocumenter``
+
+   * - ``sphinx.ext.autodoc.SlotsAttributeDocumenter``
+     - 3.4
+     - 5.0
+     - ``sphinx.ext.autodoc.AttributeDocumenter``
+
    * - ``sphinx.ext.autodoc.TypeVarDocumenter``
      - 3.4
      - 5.0

doc/usage/builders/index.rst

@@ -442,6 +442,10 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
 
       Since Sphinx-1.5, the linkcheck builder comes to use requests module.
 
+   .. versionchanged:: 3.4
+
+      The linkcheck builder retries links when servers apply rate limits.
+
 .. module:: sphinx.builders.xml
 .. class:: XMLBuilder
 

doc/usage/configuration.rst

@@ -2532,6 +2532,23 @@ Options for the linkcheck builder
 
    .. versionadded:: 2.3
 
+.. confval:: linkcheck_rate_limit_timeout
+
+   The ``linkcheck`` builder may issue a large number of requests to the same
+   site over a short period of time. This setting controls the builder behavior
+   when servers indicate that requests are rate-limited.
+
+   If a server indicates when to retry (using the `Retry-After`_ header),
+   ``linkcheck`` always follows the server indication.
+
+   Otherwise, ``linkcheck`` waits for a minute before to retry and keeps
+   doubling the wait time between attempts until it succeeds or exceeds the
+   ``linkcheck_rate_limit_timeout``. By default, the timeout is 5 minutes.
+
+   .. _Retry-After: https://tools.ietf.org/html/rfc7231#section-7.1.3
+
+   .. versionadded:: 3.4
+
 
 Options for the XML builder
 ---------------------------

doc/usage/extensions/example_google.py

@@ -294,3 +294,21 @@ class ExampleClass:
 
     def _private_without_docstring(self):
         pass
+
+class ExamplePEP526Class:
+    """The summary line for a class docstring should fit on one line.
+
+    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. If ``napoleon_attr_annotations``
+    is True, types can be specified in the class body using ``PEP 526``
+    annotations.
+
+    Attributes:
+        attr1: Description of `attr1`.
+        attr2: Description of `attr2`.
+
+    """
+
+    attr1: str
+    attr2: int

doc/usage/extensions/intersphinx.rst

@@ -75,8 +75,9 @@ linking:
    A dictionary mapping unique identifiers to a tuple ``(target, inventory)``.
    Each ``target`` is the base URI of a foreign Sphinx documentation set and can
    be a local path or an HTTP URI.  The ``inventory`` indicates where the
-   inventory file can be found: it can be ``None`` (at the same location as
-   the base URI) or another local or HTTP URI.
+   inventory file can be found: it can be ``None`` (an :file:`objects.inv` file
+   at the same location as the base URI) or another local file path or a full
+   HTTP URI to an inventory file.
 
    The unique identifier can be used to prefix cross-reference targets, so that
    it is clear which intersphinx set the target belongs to.  A link like
@@ -106,7 +107,7 @@ linking:
    ``https://docs.python.org/3``.  It is up to you to update the inventory file
    as new objects are added to the Python documentation.
 
-   **Multiple target for the inventory**
+   **Multiple targets for the inventory**
 
    .. versionadded:: 1.3
 
@@ -120,6 +121,16 @@ linking:
       intersphinx_mapping = {'python': ('https://docs.python.org/3',
                                         (None, 'python-inv.txt'))}
 
+   For a set of books edited and tested locally and then published
+   together, it could be helpful to try a local inventory file first,
+   to check references before publication::
+
+      intersphinx_mapping = {
+          'otherbook':
+              ('https://myproj.readthedocs.io/projects/otherbook/en/latest',
+                  ('../../otherbook/build/html/objects.inv', None)),
+      }
+
 .. confval:: intersphinx_cache_limit
 
    The maximum number of days to cache remote inventories.  The default is

doc/usage/extensions/napoleon.rst

@@ -203,7 +203,8 @@ Type Annotations
 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.
+analysis. `PEP 484`_ was then extended by `PEP 526`_ which introduced
+a similar way to annotate variables (and attributes).
 
 Google style with Python 3 type annotations::
 
@@ -221,6 +222,19 @@ Google style with Python 3 type annotations::
 
         """
         return True
+    
+    class Class:
+        """Summary line.
+
+        Extended description of class
+
+        Attributes:
+            attr1: Description of attr1
+            attr2: Description of attr2
+        """
+
+        attr1: int
+        attr2: str
 
 Google style with types in docstrings::
 
@@ -238,6 +252,16 @@ Google style with types in docstrings::
 
         """
         return True
+    
+    class Class:
+        """Summary line.
+
+        Extended description of class
+
+        Attributes:
+            attr1 (int): Description of attr1
+            attr2 (str): Description of attr2
+        """
 
 .. Note::
    `Python 2/3 compatible annotations`_ aren't currently
@@ -246,6 +270,9 @@ Google style with types in docstrings::
 .. _PEP 484:
    https://www.python.org/dev/peps/pep-0484/
 
+.. _PEP 526:
+    https://www.python.org/dev/peps/pep-0526/
+
 .. _Python 2/3 compatible annotations:
    https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
 
@@ -275,6 +302,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
     napoleon_use_param = True
     napoleon_use_rtype = True
     napoleon_type_aliases = None
+    napoleon_attr_annotations = True
 
 .. _Google style:
    https://google.github.io/styleguide/pyguide.html
@@ -511,3 +539,11 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
        :type arg2: :term:`dict-like <mapping>`
 
    .. versionadded:: 3.2
+
+.. confval:: napoleon_attr_annotations
+
+   True to allow using `PEP 526`_ attributes annotations in classes.
+   If an attribute is documented in the docstring without a type and
+   has an annotation in the class body, that type is used.
+
+   .. versionadded:: 3.4