Merge branch '2.0'

.travis.yml

@@ -19,7 +19,7 @@ matrix:
         - TOXENV=du13
     - python: '3.7'
       env:
-        - TOXENV=py37
+        - TOXENV=du14
         - PYTEST_ADDOPTS="--cov ./ --cov-append --cov-config setup.cfg"
     - python: 'nightly'
       env: TOXENV=py38

CHANGES

@@ -1,3 +1,4 @@
+<<<<<<< HEAD
 Release 3.0.0 (in development)
 ==============================
 
@@ -26,7 +27,7 @@ Bugs fixed
 Testing
 --------
 
-Release 2.2.0 (in development)
+Release 2.3.0 (in development)
 ==============================
 
 Dependencies
@@ -35,7 +36,26 @@ Dependencies
 Incompatible changes
 --------------------
 
+Deprecated
+----------
+
+Features added
+--------------
+
+Bugs fixed
+----------
+
+Testing
+--------
+
+Release 2.2.0 (released Aug 19, 2019)
+=====================================
+
+Incompatible changes
+--------------------
+
 * apidoc: template files are renamed to ``.rst_t``
+* html: Field lists will be styled by grid layout
 
 Deprecated
 ----------
@@ -63,6 +83,9 @@ Features added
 * #6310: imgmath: let :confval:`imgmath_use_preview` work also with the SVG
   format for images rendering inline math
 * #6533: LaTeX: refactor visit_enumerated_list() to use ``\sphinxsetlistlabels``
+* #6628: quickstart: Use ``https://docs.python.org/3/`` for default setting of
+  :confval:`intersphinx_mapping`
+* #6419: sphinx-build: give reasons why rebuilded
 
 Bugs fixed
 ----------
@@ -78,6 +101,9 @@ Bugs fixed
   ``__init__()`` and ``__new__()``
 * #6574: autodoc: :confval:`autodoc_member_order` does not refer order of
   imports when ``'bysource'`` order
+* #6574: autodoc: missing type annotation for variadic and keyword parameters
+* #6589: autodoc: Formatting issues with autodoc_typehints='none'
+* #6605: autodoc: crashed when target code contains custom method-like objects
 * #6498: autosummary: crashed with wrong autosummary_generate setting
 * #6507: autosummary: crashes without no autosummary_generate setting
 * #6511: LaTeX: autonumbered list can not be customized in LaTeX
@@ -92,30 +118,8 @@ Bugs fixed
 * #6561: glossary: Wrong hyperlinks are generated for non alphanumeric terms
 * #6620: i18n: classifiers of definition list are not translated with
   docutils-0.15
-
-Testing
---------
-
-Release 2.1.3 (in development)
-==============================
-
-Dependencies
-------------
-
-Incompatible changes
---------------------
-
-Deprecated
-----------
-
-Features added
---------------
-
-Bugs fixed
-----------
-
-Testing
---------
+* #6474: ``DocFieldTransformer`` raises AttributeError when given directive is
+  not a subclass of ObjectDescription
 
 Release 2.1.2 (released Jun 19, 2019)
 =====================================

doc/usage/extensions/math.rst

@@ -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

sphinx/builders/__init__.py

@@ -388,9 +388,11 @@ def read(self) -> List[str]:
             # ... but not those that already were removed
             changed.update(self.env.glob_toctrees & self.env.found_docs)
 
-        if changed:
-            reason = CONFIG_CHANGED_REASON.get(self.env.config_status, '')
+        if updated:  # explain the change iff build config status was not ok
+            reason = (CONFIG_CHANGED_REASON.get(self.env.config_status, '') +
+                      (self.env.config_status_extra or ''))
             logger.info('[%s] ', reason, nonl=True)
+
         logger.info(__('%s added, %s changed, %s removed'),
                     len(added), len(changed), len(removed))
 

sphinx/deprecation.py

@@ -31,10 +31,7 @@ class RemovedInSphinx50Warning(PendingDeprecationWarning):
 
 def deprecated_alias(modname, objects, warning):
     # type: (str, Dict, Type[Warning]) -> None
-    module = sys.modules.get(modname)
-    if module is None:
-        module = import_module(modname)
-
+    module = import_module(modname)
     sys.modules[modname] = _ModuleWrapper(module, modname, objects, warning)  # type: ignore
 
 

sphinx/environment/__init__.py

@@ -93,14 +93,15 @@ class BuildEnvironment:
     # --------- ENVIRONMENT INITIALIZATION -------------------------------------
 
     def __init__(self, app: "Sphinx" = None):
-        self.app = None             # type: Sphinx
-        self.doctreedir = None      # type: str
-        self.srcdir = None          # type: str
-        self.config = None          # type: Config
-        self.config_status = None   # type: int
-        self.events = None          # type: EventManager
-        self.project = None         # type: Project
-        self.version = None         # type: Dict[str, str]
+        self.app = None                  # type: Sphinx
+        self.doctreedir = None           # type: str
+        self.srcdir = None               # type: str
+        self.config = None               # type: Config
+        self.config_status = None        # type: int
+        self.config_status_extra = None  # type: str
+        self.events = None               # type: EventManager
+        self.project = None              # type: Project
+        self.version = None              # type: Dict[str, str]
 
         # the method of doctree versioning; see set_versioning_method
         self.versioning_condition = None  # type: Union[bool, Callable]
@@ -230,16 +231,25 @@ def setup(self, app: "Sphinx") -> None:
     def _update_config(self, config: Config) -> None:
         """Update configurations by new one."""
         self.config_status = CONFIG_OK
+        self.config_status_extra = ''
         if self.config is None:
             self.config_status = CONFIG_NEW
         elif self.config.extensions != config.extensions:
             self.config_status = CONFIG_EXTENSIONS_CHANGED
+            extensions = sorted(
+                set(self.config.extensions) ^ set(config.extensions))
+            if len(extensions) == 1:
+                extension = extensions[0]
+            else:
+                extension = '%d' % (len(extensions),)
+            self.config_status_extra = ' (%r)' % (extension,)
         else:
             # check if a config value was changed that affects how
             # doctrees are read
             for item in config.filter('env'):
                 if self.config[item.name] != item.value:
                     self.config_status = CONFIG_CHANGED
+                    self.config_status_extra = ' (%r)' % (item.name,)
                     break
 
         self.config = config

sphinx/ext/autodoc/importer.py

@@ -8,7 +8,7 @@
     :license: BSD, see LICENSE for details.
 """
 
-import sys
+import importlib
 import traceback
 import warnings
 from collections import namedtuple
@@ -23,14 +23,13 @@
 
 def import_module(modname: str, warningiserror: bool = False) -> Any:
     """
-    Call __import__(modname), convert exceptions to ImportError
+    Call importlib.import_module(modname), convert exceptions to ImportError
     """
     try:
         with warnings.catch_warnings():
             warnings.filterwarnings("ignore", category=ImportWarning)
             with logging.skip_warningiserror(not warningiserror):
-                __import__(modname)
-                return sys.modules[modname]
+                return importlib.import_module(modname)
     except BaseException as exc:
         # Importing modules may cause any side effects, including
         # SystemExit, so we need to catch all errors.

sphinx/ext/coverage.py

@@ -13,6 +13,7 @@
 import inspect
 import pickle
 import re
+from importlib import import_module
 from os import path
 from typing import Any, Dict, IO, List, Pattern, Set, Tuple
 
@@ -144,7 +145,7 @@ def build_py_coverage(self) -> None:
                 continue
 
             try:
-                mod = __import__(mod_name, fromlist=['foo'])
+                mod = import_module(mod_name)
             except ImportError as err:
                 logger.warning(__('module %s could not be imported: %s'), mod_name, err)
                 self.py_undoc[mod_name] = {'error': err}

sphinx/ext/inheritance_diagram.py

@@ -38,8 +38,8 @@ class E(B): pass
 import builtins
 import inspect
 import re
-import sys
 from hashlib import md5
+from importlib import import_module
 from typing import Any, Dict, Iterable, List, Tuple
 from typing import cast
 
@@ -74,8 +74,10 @@ def try_import(objname: str) -> Any:
     Returns imported object or module.  If failed, returns None value.
     """
     try:
-        __import__(objname)
-        return sys.modules.get(objname)
+        return import_module(objname)
+    except TypeError:
+        # Relative import
+        return None
     except ImportError:
         matched = module_sig_re.match(objname)
 
@@ -87,8 +89,8 @@ def try_import(objname: str) -> Any:
         if modname is None:
             return None
         try:
-            __import__(modname)
-            return getattr(sys.modules.get(modname), attrname, None)
+            module = import_module(modname)
+            return getattr(module, attrname, None)
         except ImportError:
             return None
 

sphinx/highlighting.py

@@ -9,6 +9,7 @@
 """
 
 from functools import partial
+from importlib import import_module
 
 from pygments import highlight
 from pygments.filters import ErrorToken
@@ -83,7 +84,7 @@ def get_style(self, stylename):
             return NoneStyle
         elif '.' in stylename:
             module, stylename = stylename.rsplit('.', 1)
-            return getattr(__import__(module, None, None, ['__name__']), stylename)
+            return getattr(import_module(module), stylename)
         else:
             return get_style_by_name(stylename)
 

sphinx/registry.py

@@ -9,6 +9,7 @@
 """
 
 import traceback
+from importlib import import_module
 from types import MethodType
 
 from docutils.parsers.rst import Directive
@@ -419,18 +420,19 @@ def load_extension(self, app, extname):
         prefix = __('while setting up extension %s:') % extname
         with prefixed_warnings(prefix):
             try:
-                mod = __import__(extname, None, None, ['setup'])
+                mod = import_module(extname)
             except ImportError as err:
                 logger.verbose(__('Original exception:\n') + traceback.format_exc())
                 raise ExtensionError(__('Could not import extension %s') % extname, err)
 
-            if not hasattr(mod, 'setup'):
+            setup = getattr(mod, 'setup', None)
+            if setup is None:
                 logger.warning(__('extension %r has no setup() function; is it really '
                                   'a Sphinx extension module?'), extname)
                 metadata = {}  # type: Dict[str, Any]
             else:
                 try:
-                    metadata = mod.setup(app)
+                    metadata = setup(app)
                 except VersionRequirementError as err:
                     # add the extension name to the version required
                     raise VersionRequirementError(

sphinx/search/__init__.py

@@ -11,6 +11,7 @@
 import pickle
 import re
 import warnings
+from importlib import import_module
 from os import path
 
 from docutils import nodes
@@ -278,8 +279,7 @@ def __init__(self, env, lang, options, scoring):
             self.lang = SearchEnglish(options)  # type: SearchLanguage
         elif isinstance(lang_class, str):
             module, classname = lang_class.rsplit('.', 1)
-            lang_class = getattr(__import__(module, None, None, [classname]),
-                                 classname)
+            lang_class = getattr(import_module(module), classname)
             self.lang = lang_class(options)
         else:
             # it's directly a class (e.g. added by app.add_search_language)

sphinx/templates/quickstart/conf.py_t

@@ -2,7 +2,7 @@
 #
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Path setup --------------------------------------------------------------
 
@@ -105,7 +105,7 @@ html_static_path = ['{{ dot }}static']
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/3/': None}
 {%- endif %}
 {%- if 'sphinx.ext.todo' in extensions %}
 
@@ -114,4 +114,3 @@ intersphinx_mapping = {'https://docs.python.org/': None}
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 {%- endif %}
-

sphinx/themes/basic/static/basic.css_t

@@ -520,23 +520,24 @@ dl.citation > dd:after {
 }
 
 dl.field-list {
-    display: flex;
-    flex-wrap: wrap;
+    display: grid;
+    grid-template-columns: fit-content(30%) auto;
 }
 
 dl.field-list > dt {
-    flex-basis: 20%;
     font-weight: bold;
     word-break: break-word;
+    padding-left: 0.5em;
+    padding-right: 5px;
 }
 
 dl.field-list > dt:after {
     content: ":";
 }
 
 dl.field-list > dd {
-    flex-basis: 70%;
-    padding-left: 1em;
+    padding-left: 0.5em;
+    margin-top: 0em;
     margin-left: 0em;
     margin-bottom: 0em;
 }