diff --git a/CHANGES b/CHANGES
index aaa6ed0a7..b3dbaaab4 100644
--- a/CHANGES
+++ b/CHANGES
@@ -41,11 +41,20 @@ Deprecated
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
+* #9872: html: Class namespace collision between autodoc signatures and
+ docutils-0.17
+* #9864: mathjax: Failed to render equations via MathJax v2. The loading method
+ of MathJax is back to "async" method again
Testing
--------
diff --git a/doc/usage/extensions/math.rst b/doc/usage/extensions/math.rst
index 764bf5dd3..626306089 100644
--- a/doc/usage/extensions/math.rst
+++ b/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).
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index 62f1fb1b3..157e57e3a 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -1704,7 +1704,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
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)
diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py
index 09ec8d1db..30d038d84 100644
--- a/sphinx/ext/mathjax.py
+++ b/sphinx/ext/mathjax.py
@@ -92,10 +92,17 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: Dict
body = 'window.MathJax = %s' % json.dumps(app.config.mathjax3_config)
app.add_js_file(None, body=body)
- 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)
def setup(app: Sphinx) -> Dict[str, Any]:
diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py
index 3a39bde1d..24ea49ae0 100644
--- a/sphinx/util/inspect.py
+++ b/sphinx/util/inspect.py
@@ -871,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)
@@ -879,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:
@@ -888,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
diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py
index 15fd15449..bba07f447 100644
--- a/sphinx/writers/html5.py
+++ b/sphinx/writers/html5.py
@@ -13,7 +13,7 @@ import posixpath
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 ... will be
+ # converted to ... by `visit_inline`.
+ supported_inline_tags: Set[str] = set()
def __init__(self, document: nodes.document, builder: Builder) -> None:
super().__init__(document, builder)
diff --git a/tests/test_ext_math.py b/tests/test_ext_math.py
index 7c78954b7..175c9e0f5 100644
--- a/tests/test_ext_math.py
+++ b/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 ('' 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 ('' 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 ('' 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 ('