Merge branch '3.x'

.circleci/config.yml

@@ -3,6 +3,8 @@ jobs:
   build:
     docker:
       - image: sphinxdoc/docker-ci
+        environment:
+          DO_EPUBCHECK: 1
     working_directory: /sphinx
     steps:
       - checkout

CHANGES

@@ -51,36 +51,69 @@ Incompatible changes
 Deprecated
 ----------
 
+* C, parsing of pre-v3 style type directives and roles, along with the options
+  :confval:`c_allow_pre_v3` and :confval:`c_warn_on_allowed_pre_v3`.
+
 Features added
 --------------
 
+* #2076: autodoc: Allow overriding of exclude-members in skip-member function
+* #2024: autosummary: Add :confval:`autosummary_filename_map` to avoid conflict
+  of filenames between two object with different case
 * #7849: html: Add :confval:`html_codeblock_linenos_style` to change the style
   of line numbers for code-blocks
 * #7853: C and C++, support parameterized GNU style attributes.
 * #7888: napoleon: Add aliases Warn and Raise.
 * C, added :rst:dir:`c:alias` directive for inserting copies
   of existing declarations.
+* #7745: html: inventory is broken if the docname contains a space
+* #7902: html theme: Add a new option :confval:`globaltoc_maxdepth` to control
+  the behavior of globaltoc in sidebar
+* #7840: i18n: Optimize the dependencies check on bootstrap
+* #5208: linkcheck: Support checks for local links
+* #5090: setuptools: Link verbosity to distutils' -v and -q option
 * #7052: add ``:noindexentry:`` to the Python, C, C++, and Javascript domains.
   Update the documentation to better reflect the relationship between this option
   and the ``:noindex:`` option.
+* #7899: C, add possibility of parsing of some pre-v3 style type directives and
+  roles and try to convert them to equivalent v3 directives/roles.
+  Set the new option :confval:`c_allow_pre_v3` to ``True`` to enable this.
+  The warnings printed from this functionality can be suppressed by setting
+  :confval:`c_warn_on_allowed_pre_v3`` to ``True``.
+  The functionality is immediately deprecated.
 
 Bugs fixed
 ----------
 
 * #7886: autodoc: TypeError is raised on mocking generic-typed classes
+* #7935: autodoc: function signature is not shown when the function has a
+  parameter having ``inspect._empty`` as its default value
+* #7901: autodoc: type annotations for overloaded functions are not resolved
+* #904: autodoc: An instance attribute cause a crash of autofunction directive
+* #1362: autodoc: ``private-members`` option does not work for class attributes
+* #7983: autodoc: Generator type annotation is wrongly rendered in py36
 * #7839: autosummary: cannot handle umlauts in function names
 * #7865: autosummary: Failed to extract summary line when abbreviations found
 * #7866: autosummary: Failed to extract correct summary line when docstring
   contains a hyperlink target
+* #7469: autosummary: "Module attributes" header is not translatable
+* #7940: apidoc: An extra newline is generated at the end of the rst file if a
+  module has submodules 
 * #4258: napoleon: decorated special methods are not shown
 * #7715: LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links
 * #7846: html theme: XML-invalid files were generated
 * #7894: gettext: Wrong source info is shown when using rst_epilog
+* #7691: linkcheck: HEAD requests are not used for checking
+* #4888: i18n: Failed to add an explicit title to ``:ref:`` role on translation
+* #7928: py domain: failed to resolve a type annotation for the attribute
+* #7968: i18n: The content of ``math`` directive is interpreted as reST on
+  translation
 * #7869: :rst:role:`abbr` role without an explanation will show the explanation
   from the previous abbr role
 * C and C++, removed ``noindex`` directive option as it did
   nothing.
 * #7619: Duplicated node IDs are generated if node has multiple IDs
+* #2050: Symbols sections are appeared twice in the index page
 
 Testing
 --------
@@ -103,6 +136,9 @@ Features added
 Bugs fixed
 ----------
 
+* C, don't deepcopy the entire symbol table and make a mess every time an
+  enumerator is handled.
+
 Testing
 --------
 
@@ -626,7 +662,7 @@ Release 2.4.1 (released Feb 11, 2020)
 Bugs fixed
 ----------
 
-* #7120: html: crashed when on scaling SVG images which have float dimentions
+* #7120: html: crashed when on scaling SVG images which have float dimensions
 * #7126: autodoc: TypeError: 'getset_descriptor' object is not iterable
 
 Release 2.4.0 (released Feb 09, 2020)
@@ -772,7 +808,7 @@ Features added
 * #6548: html: Use favicon for OpenSearch if available
 * #6729: html theme: agogo theme now supports ``rightsidebar`` option
 * #6780: Add PEP-561 Support
-* #6762: latex: Allow to load additonal LaTeX packages via ``extrapackages`` key
+* #6762: latex: Allow to load additional LaTeX packages via ``extrapackages`` key
   of :confval:`latex_elements`
 * #1331: Add new config variable: :confval:`user_agent`
 * #6000: LaTeX: have backslash also be an inline literal word wrap break

EXAMPLES

@@ -363,7 +363,7 @@ Documentation using a custom theme or integrated in a website
 * `Roundup <http://www.roundup-tracker.org/>`__
 * `SaltStack <https://docs.saltstack.com/>`__
 * `scikit-learn <http://scikit-learn.org/stable/>`__
-* `SciPy <https://docs.scipy.org/doc/scipy/refrence/>`__
+* `SciPy <https://docs.scipy.org/doc/scipy/reference/>`__
 * `Scrapy <https://doc.scrapy.org/>`__
 * `Seaborn <https://seaborn.pydata.org/>`__
 * `Selenium <https://docs.seleniumhq.org/docs/>`__
@@ -390,6 +390,7 @@ Homepages and other non-documentation sites
 * `Pylearn2 <http://www.deeplearning.net/software/pylearn2/>`__ (sphinxdoc, customized)
 * `PyXLL <https://www.pyxll.com/>`__ (sphinx_bootstrap_theme, customized)
 * `SciPy Cookbook <https://scipy-cookbook.readthedocs.io/>`__ (sphinx_rtd_theme)
+* `Tech writer at work blog <https://blog.documatt.com/>`__ (custom theme)
 * `The Wine Cellar Book <https://www.thewinecellarbook.com/doc/en/>`__ (sphinxdoc)
 * `Thomas Cokelaer's Python, Sphinx and reStructuredText tutorials <https://thomas-cokelaer.info/tutorials/>`__ (standard)
 * `UC Berkeley ME233 Advanced Control Systems II course <https://berkeley-me233.github.io/>`__ (sphinxdoc)

README.rst

@@ -30,6 +30,10 @@
    :target: https://opensource.org/licenses/BSD-3-Clause
    :alt: BSD 3 Clause
 
+.. image:: https://codetriage.com/sphinx-doc/sphinx/badges/users.svg
+   :target: https://codetriage.com/sphinx-doc/sphinx
+   :alt: Open Source Helpers badge
+
 Sphinx is a tool that makes it easy to create intelligent and beautiful
 documentation for Python projects (or other documents consisting of multiple
 reStructuredText sources), written by Georg Brandl.  It was originally created

doc/usage/configuration.rst

@@ -2546,6 +2546,23 @@ Options for the C domain
 
    .. versionadded:: 3.0
 
+.. confval:: c_allow_pre_v3
+
+   A boolean (default ``False``) controlling whether to parse and try to
+   convert pre-v3 style type directives and type roles.
+
+   .. versionadded:: 3.2
+   .. deprecated:: 3.2
+      Use the directives and roles added in v3.
+
+.. confval:: c_warn_on_allowed_pre_v3
+
+   A boolean (default ``True``) controlling whether to warn when a pre-v3
+   style type directive/role is parsed and converted.
+
+   .. versionadded:: 3.2
+   .. deprecated:: 3.2
+      Use the directives and roles added in v3.
 
 .. _cpp-config:
 

doc/usage/extensions/autosummary.rst

@@ -175,7 +175,7 @@ also use these config values:
 
 .. confval:: autosummary_generate_overwrite
 
-   If true, autosummary already overwrites stub files by generated contents.
+   If true, autosummary overwrites existing files by generated stub pages.
    Defaults to true (enabled).
 
    .. versionadded:: 3.0
@@ -195,6 +195,15 @@ also use these config values:
 
    .. versionadded:: 2.1
 
+.. confval:: autosummary_filename_map
+
+   A dict mapping object names to filenames. This is necessary to avoid
+   filename conflicts where multiple objects have names that are
+   indistinguishable when case is ignored, on file systems where filenames
+   are case-insensitive.
+
+   .. versionadded:: 3.2
+
 
 Customizing templates
 ---------------------

doc/usage/theming.rst

@@ -172,6 +172,12 @@ These themes are:
 
     .. versionadded:: 3.1
 
+  - **globaltoc_maxdepth** (int): The maximum depth of the toctree in
+    ``globaltoc.html`` (see :confval:`html_sidebars`).  Set it to -1 to allow
+    unlimited depth. Defaults to the max depth selected in the toctree directive.
+
+    .. versionadded:: 3.2
+
 **alabaster**
   `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
   (especially as used in his Requests project), which was itself originally

sphinx/builders/_epub_base.py

@@ -393,7 +393,7 @@ def is_vector_graphics(self, filename: str) -> bool:
         return ext in VECTOR_GRAPHICS_EXTENSIONS
 
     def copy_image_files_pil(self) -> None:
-        """Copy images using Pillow, the Python Imaging Libary.
+        """Copy images using Pillow, the Python Imaging Library.
         The method tries to read and write the files with Pillow, converting
         the format and resizing the image if necessary/possible.
         """

sphinx/builders/dirhtml.py

@@ -49,9 +49,12 @@ def get_outfilename(self, pagename: str) -> str:
 # for compatibility
 deprecated_alias('sphinx.builders.html',
                  {
-                     'DirectoryHTMLBuilder': DirectoryHTMLBuilder,
+                     'DirectoryHTMLBuilder':  DirectoryHTMLBuilder,
                  },
-                 RemovedInSphinx40Warning)
+                 RemovedInSphinx40Warning,
+                 {
+                     'DirectoryHTMLBuilder': 'sphinx.builders.dirhtml.DirectoryHTMLBuilder',
+                 })
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:

sphinx/builders/html/__init__.py

@@ -15,6 +15,7 @@
 from datetime import datetime
 from os import path
 from typing import Any, Dict, IO, Iterable, Iterator, List, Set, Tuple, Type
+from urllib.parse import quote
 
 from docutils import nodes
 from docutils.core import publish_parts
@@ -881,6 +882,8 @@ def index_page(self, pagename: str, doctree: nodes.document, title: str) -> None
     def _get_local_toctree(self, docname: str, collapse: bool = True, **kwargs: Any) -> str:
         if 'includehidden' not in kwargs:
             kwargs['includehidden'] = False
+        if kwargs.get('maxdepth') == '':
+            kwargs.pop('maxdepth')
         return self.render_partial(TocTree(self.env).get_toctree_for(
             docname, self, collapse, **kwargs))['fragment']
 
@@ -940,7 +943,7 @@ def has_wildcard(pattern: str) -> bool:
     # --------- these are overwritten by the serialization builder
 
     def get_target_uri(self, docname: str, typ: str = None) -> str:
-        return docname + self.link_suffix
+        return quote(docname) + self.link_suffix
 
     def handle_page(self, pagename: str, addctx: Dict, templatename: str = 'page.html',
                     outfilename: str = None, event_arg: Any = None) -> None:

sphinx/builders/linkcheck.py

@@ -35,6 +35,8 @@
 
 logger = logging.getLogger(__name__)
 
+uri_re = re.compile('[a-z]+://')
+
 
 DEFAULT_REQUEST_HEADERS = {
     'Accept': 'text/html,application/xhtml+xml;q=0.9,*/*;q=0.8',
@@ -210,10 +212,21 @@ def check_uri() -> Tuple[str, str, int]:
 
         def check() -> Tuple[str, str, int]:
             # check for various conditions without bothering the network
-            if len(uri) == 0 or uri.startswith(('#', 'mailto:', 'ftp:')):
+            if len(uri) == 0 or uri.startswith(('#', 'mailto:')):
                 return 'unchecked', '', 0
             elif not uri.startswith(('http:', 'https:')):
-                return 'local', '', 0
+                if uri_re.match(uri):
+                    # non supported URI schemes (ex. ftp)
+                    return 'unchecked', '', 0
+                else:
+                    if path.exists(path.join(self.srcdir, uri)):
+                        return 'working', '', 0
+                    else:
+                        for rex in self.to_ignore:
+                            if rex.match(uri):
+                                return 'ignored', '', 0
+                        else:
+                            return 'broken', '', 0
             elif uri in self.good:
                 return 'working', 'old', 0
             elif uri in self.broken:

sphinx/builders/singlehtml.py

@@ -193,7 +193,11 @@ def write_additional_files(self) -> None:
                  {
                      'SingleFileHTMLBuilder': SingleFileHTMLBuilder,
                  },
-                 RemovedInSphinx40Warning)
+                 RemovedInSphinx40Warning,
+                 {
+                     'SingleFileHTMLBuilder':
+                     'sphinx.builders.singlehtml.SingleFileHTMLBuilder',
+                 })
 
 
 def setup(app: Sphinx) -> Dict[str, Any]:

sphinx/deprecation.py

@@ -29,27 +29,39 @@ class RemovedInSphinx60Warning(PendingDeprecationWarning):
 RemovedInNextVersionWarning = RemovedInSphinx50Warning
 
 
-def deprecated_alias(modname: str, objects: Dict, warning: "Type[Warning]") -> None:
+def deprecated_alias(modname: str, objects: Dict[str, object],
+                     warning: "Type[Warning]", names: Dict[str, str] = None) -> None:
     module = import_module(modname)
-    sys.modules[modname] = _ModuleWrapper(module, modname, objects, warning)  # type: ignore
+    sys.modules[modname] = _ModuleWrapper(  # type: ignore
+        module, modname, objects, warning, names)
 
 
 class _ModuleWrapper:
-    def __init__(self, module: Any, modname: str, objects: Dict, warning: "Type[Warning]"
-                 ) -> None:
+    def __init__(self, module: Any, modname: str,
+                 objects: Dict[str, object],
+                 warning: "Type[Warning]",
+                 names: Dict[str, str]) -> None:
         self._module = module
         self._modname = modname
         self._objects = objects
         self._warning = warning
+        self._names = names
 
     def __getattr__(self, name: str) -> Any:
-        if name in self._objects:
-            warnings.warn("%s.%s is deprecated. Check CHANGES for Sphinx "
-                          "API modifications." % (self._modname, name),
+        if name not in self._objects:
+            return getattr(self._module, name)
+
+        canonical_name = self._names.get(name, None)
+        if canonical_name is not None:
+            warnings.warn(
+                "The alias '{}.{}' is deprecated, use '{}' instead. Check CHANGES for "
+                "Sphinx API modifications.".format(self._modname, name, canonical_name),
+                self._warning, stacklevel=3)
+        else:
+            warnings.warn("{}.{} is deprecated. Check CHANGES for Sphinx "
+                          "API modifications.".format(self._modname, name),
                           self._warning, stacklevel=3)
-            return self._objects[name]
-
-        return getattr(self._module, name)
+        return self._objects[name]
 
 
 class DeprecatedDict(dict):

sphinx/directives/__init__.py

@@ -268,7 +268,10 @@ def run(self) -> List[Node]:
                  {
                      'DescDirective': ObjectDescription,
                  },
-                 RemovedInSphinx50Warning)
+                 RemovedInSphinx50Warning,
+                 {
+                     'DescDirective': 'sphinx.directives.ObjectDescription',
+                 })
 
 
 def setup(app: "Sphinx") -> Dict[str, Any]: