CHANGES

@@ -1,3 +1,27 @@
+Release 4.3.1 (released Nov 28, 2021)
+=====================================
+
+Features added
+--------------
+
+* #9864: mathjax: Support chnaging the loading method of MathJax to "defer" via
+  :confval:`mathjax_options`
+
+Bugs fixed
+----------
+
+* #9838: autodoc: AttributeError is raised on building document for functions
+  decorated by functools.lru_cache
+* #9879: autodoc: AttributeError is raised on building document for an object
+  having invalid __doc__ atribute
+* #9844: autodoc: Failed to process a function wrapped with functools.partial if
+  :confval:`autodoc_preserve_defaults` enabled
+* #9872: html: Class namespace collision between autodoc signatures and
+  docutils-0.17
+* #9868: imgmath: Crashed if the dvisvgm command failed to convert equation
+* #9864: mathjax: Failed to render equations via MathJax v2.  The loading method
+  of MathJax is back to "async" method again
+
 Release 4.3.0 (released Nov 11, 2021)
 =====================================
 

doc/usage/extensions/math.rst

@@ -200,6 +200,11 @@ Sphinx but is set to automatically include it from a third-party site.
 
    .. versionadded:: 1.8
 
+   .. versionchanged:: 4.4.1
+
+      Allow to change the loading method (async or defer) of MathJax if "async"
+      or "defer" key is set.
+
 .. confval:: mathjax3_config
 
    The configuration options for MathJax v3 (which is used by default).

sphinx/__init__.py

@@ -27,8 +27,8 @@
 warnings.filterwarnings('ignore', "'U' mode is deprecated",
                         DeprecationWarning, module='docutils.io')
 
-__version__ = '4.3.0'
-__released__ = '4.3.0'  # used when Sphinx builds its own docs
+__version__ = '4.3.1'
+__released__ = '4.3.1'  # used when Sphinx builds its own docs
 
 #: Version info for better programmatic use.
 #:
@@ -38,7 +38,7 @@
 #:
 #: .. versionadded:: 1.2
 #:    Before version 1.2, check the string ``sphinx.__version__``.
-version_info = (4, 3, 0, 'final', 0)
+version_info = (4, 3, 1, 'final', 0)
 
 package_dir = path.abspath(path.dirname(__file__))
 

sphinx/ext/autodoc/__init__.py

@@ -1704,7 +1704,7 @@ def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
         classdoc_from = self.options.get('class-doc-from', self.config.autoclass_content)
 
         docstrings = []
-        attrdocstring = self.get_attr(self.object, '__doc__', None)
+        attrdocstring = getdoc(self.object, self.get_attr)
         if attrdocstring:
             docstrings.append(attrdocstring)
 

sphinx/ext/autodoc/preserve_defaults.py

@@ -73,7 +73,7 @@ def update_defvalue(app: Sphinx, obj: Any, bound_method: bool) -> None:
         lines = inspect.getsource(obj).splitlines()
         if lines[0].startswith((' ', r'\t')):
             lines.insert(0, '')  # insert a dummy line to follow what get_function_def() does.
-    except OSError:
+    except (OSError, TypeError):
         lines = []
 
     try:

sphinx/ext/imgmath.py

@@ -12,7 +12,6 @@
 import re
 import shutil
 import subprocess
-import sys
 import tempfile
 from os import path
 from subprocess import PIPE, CalledProcessError
@@ -43,11 +42,11 @@
 class MathExtError(SphinxError):
     category = 'Math extension error'
 
-    def __init__(self, msg: str, stderr: bytes = None, stdout: bytes = None) -> None:
+    def __init__(self, msg: str, stderr: str = None, stdout: str = None) -> None:
         if stderr:
-            msg += '\n[stderr]\n' + stderr.decode(sys.getdefaultencoding(), 'replace')
+            msg += '\n[stderr]\n' + stderr
         if stdout:
-            msg += '\n[stdout]\n' + stdout.decode(sys.getdefaultencoding(), 'replace')
+            msg += '\n[stdout]\n' + stdout
         super().__init__(msg)
 
 
@@ -135,7 +134,8 @@ def compile_math(latex: str, builder: Builder) -> str:
     command.append('math.tex')
 
     try:
-        subprocess.run(command, stdout=PIPE, stderr=PIPE, cwd=tempdir, check=True)
+        subprocess.run(command, stdout=PIPE, stderr=PIPE, cwd=tempdir, check=True,
+                       encoding='ascii')
         return path.join(tempdir, 'math.dvi')
     except OSError as exc:
         logger.warning(__('LaTeX command %r cannot be run (needed for math '

sphinx/ext/mathjax.py

@@ -81,10 +81,17 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: Dict
     domain = cast(MathDomain, app.env.get_domain('math'))
     if app.registry.html_assets_policy == 'always' or domain.has_equations(pagename):
         # Enable mathjax only if equations exists
-        options = {'defer': 'defer'}
+        options = {}
         if app.config.mathjax_options:
             options.update(app.config.mathjax_options)
-        app.add_js_file(app.config.mathjax_path, **options)  # type: ignore
+        if 'async' not in options and 'defer' not in options:
+            if app.config.mathjax3_config:
+                # Load MathJax v3 via "defer" method
+                options['defer'] = 'defer'
+            else:
+                # Load other MathJax via "async" method
+                options['async'] = 'async'
+        app.add_js_file(app.config.mathjax_path, **options)
 
         if app.config.mathjax2_config:
             if app.config.mathjax_path == MATHJAX_URL:

sphinx/util/inspect.py

@@ -19,8 +19,7 @@
 import warnings
 from functools import partial, partialmethod
 from importlib import import_module
-from inspect import (Parameter, isasyncgenfunction, isclass, ismethod,  # NOQA
-                     ismethoddescriptor, ismodule)
+from inspect import Parameter, isclass, ismethod, ismethoddescriptor, ismodule  # NOQA
 from io import StringIO
 from types import ModuleType
 from typing import Any, Callable, Dict, Mapping, Optional, Sequence, Tuple, Type, cast
@@ -408,6 +407,16 @@ def iswrappedcoroutine(obj: Any) -> bool:
         return False
 
 
+def isasyncgenfunction(obj: Any) -> bool:
+    """Check if the object is async-gen function."""
+    if hasattr(obj, '__code__') and inspect.isasyncgenfunction(obj):
+        # check obj.__code__ because isasyncgenfunction() crashes for custom method-like
+        # objects on python3.7 (see https://github.com/sphinx-doc/sphinx/issues/9838)
+        return True
+    else:
+        return False
+
+
 def isproperty(obj: Any) -> bool:
     """Check if the object is property."""
     if sys.version_info >= (3, 8):
@@ -862,6 +871,13 @@ def getdoc(obj: Any, attrgetter: Callable = safe_getattr,
     * inherited docstring
     * inherited decorated methods
     """
+    def getdoc_internal(obj: Any, attrgetter: Callable = safe_getattr) -> Optional[str]:
+        doc = attrgetter(obj, '__doc__', None)
+        if isinstance(doc, str):
+            return doc
+        else:
+            return None
+
     if cls and name and isclassmethod(obj, cls, name):
         for basecls in getmro(cls):
             meth = basecls.__dict__.get(name)
@@ -870,7 +886,7 @@ def getdoc(obj: Any, attrgetter: Callable = safe_getattr,
                 if doc is not None or not allow_inherited:
                     return doc
 
-    doc = attrgetter(obj, '__doc__', None)
+    doc = getdoc_internal(obj)
     if ispartial(obj) and doc == obj.__class__.__doc__:
         return getdoc(obj.func)
     elif doc is None and allow_inherited:
@@ -879,7 +895,7 @@ def getdoc(obj: Any, attrgetter: Callable = safe_getattr,
             for basecls in getmro(cls):
                 meth = safe_getattr(basecls, name, None)
                 if meth is not None:
-                    doc = attrgetter(meth, '__doc__', None)
+                    doc = getdoc_internal(meth)
                     if doc is not None:
                         break
 

sphinx/writers/html5.py

@@ -13,7 +13,7 @@
 import re
 import urllib.parse
 import warnings
-from typing import TYPE_CHECKING, Iterable, Tuple, cast
+from typing import TYPE_CHECKING, Iterable, Set, Tuple, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node, Text
@@ -56,6 +56,10 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     """
 
     builder: "StandaloneHTMLBuilder" = None
+    # Override docutils.writers.html5_polyglot:HTMLTranslator
+    # otherwise, nodes like <inline classes="s">...</inline> will be
+    # converted to <s>...</s> by `visit_inline`.
+    supported_inline_tags: Set[str] = set()
 
     def __init__(self, document: nodes.document, builder: Builder) -> None:
         super().__init__(document, builder)

tests/test_ext_math.py

@@ -71,7 +71,7 @@ def test_mathjax_options(app, status, warning):
     app.builder.build_all()
 
     content = (app.outdir / 'index.html').read_text()
-    assert ('<script defer="defer" integrity="sha384-0123456789" '
+    assert ('<script async="async" integrity="sha384-0123456789" '
             'src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">'
             '</script>' in content)
 
@@ -221,6 +221,7 @@ def test_mathjax3_config(app, status, warning):
 
     content = (app.outdir / 'index.html').read_text()
     assert MATHJAX_URL in content
+    assert ('<script defer="defer" src="%s">' % MATHJAX_URL in content)
     assert ('<script>window.MathJax = {"extensions": ["tex2jax.js"]}</script>' in content)
 
 
@@ -231,12 +232,35 @@ def test_mathjax2_config(app, status, warning):
     app.builder.build_all()
 
     content = (app.outdir / 'index.html').read_text()
-    assert MATHJAX_URL in content
+    assert ('<script async="async" src="%s">' % MATHJAX_URL in content)
     assert ('<script type="text/x-mathjax-config">'
             'MathJax.Hub.Config({"extensions": ["tex2jax.js"]})'
             '</script>' in content)
 
 
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'mathjax_options': {'async': 'async'},
+                                   'mathjax3_config': {'extensions': ['tex2jax.js']}})
+def test_mathjax_options_async_for_mathjax3(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').read_text()
+    assert MATHJAX_URL in content
+    assert ('<script async="async" src="%s">' % MATHJAX_URL in content)
+
+
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'mathjax_options': {'defer': 'defer'},
+                                   'mathjax2_config': {'extensions': ['tex2jax.js']}})
+def test_mathjax_options_defer_for_mathjax2(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'index.html').read_text()
+    assert ('<script defer="defer" src="%s">' % MATHJAX_URL in content)
+
+
 @pytest.mark.sphinx('html', testroot='ext-math',
                     confoverrides={'extensions': ['sphinx.ext.mathjax']})
 def test_mathjax_is_installed_only_if_document_having_math(app, status, warning):

tests/test_util_inspect.py

@@ -16,7 +16,6 @@
 import types
 from inspect import Parameter
 
-import _testcapi
 import pytest
 
 from sphinx.util import inspect
@@ -627,8 +626,6 @@ class Descriptor:
         def __get__(self, obj, typ=None):
             pass
 
-    testinstancemethod = _testcapi.instancemethod(str.__repr__)
-
     assert inspect.isattributedescriptor(Base.prop) is True                    # property
     assert inspect.isattributedescriptor(Base.meth) is False                   # method
     assert inspect.isattributedescriptor(Base.staticmeth) is False             # staticmethod
@@ -639,7 +636,16 @@ def __get__(self, obj, typ=None):
     assert inspect.isattributedescriptor(dict.__dict__['fromkeys']) is False   # ClassMethodDescriptorType  # NOQA
     assert inspect.isattributedescriptor(types.FrameType.f_locals) is True     # GetSetDescriptorType       # NOQA
     assert inspect.isattributedescriptor(datetime.timedelta.days) is True      # MemberDescriptorType       # NOQA
-    assert inspect.isattributedescriptor(testinstancemethod) is False          # instancemethod (C-API)     # NOQA
+
+    try:
+        # _testcapi module cannot be importable in some distro
+        # refs: https://github.com/sphinx-doc/sphinx/issues/9868
+        import _testcapi
+
+        testinstancemethod = _testcapi.instancemethod(str.__repr__)
+        assert inspect.isattributedescriptor(testinstancemethod) is False      # instancemethod (C-API)     # NOQA
+    except ImportError:
+        pass
 
 
 def test_isproperty(app):