Merge branch '4.x'

13 files changed, 206 insertions, 40 deletions

diff --git a/tests/roots/test-ext-autodoc/target/annotations.py b/tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py
index ef600e2af..d8a2fecef 100644
--- a/tests/roots/test-ext-autodoc/target/annotations.py
+++ b/tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import io
 from typing import overload
 
 myint = int
@@ -11,6 +12,10 @@ variable: myint
 variable2 = None  # type: myint
 
 
+def read(r: io.BytesIO) -> io.StringIO:
+    """docstring"""
+
+
 def sum(x: myint, y: myint) -> myint:
     """docstring"""
     return x + y
diff --git a/tests/roots/test-ext-autodoc/target/metadata.py b/tests/roots/test-ext-autodoc/target/metadata.py
new file mode 100644
index 000000000..7a4488f67
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/metadata.py
@@ -0,0 +1,2 @@
+def foo():
+    """:meta metadata-only-docstring:"""
diff --git a/tests/roots/test-ext-autodoc/target/singledispatch.py b/tests/roots/test-ext-autodoc/target/singledispatch.py
index 3fa81dcae..fca2b6683 100644
--- a/tests/roots/test-ext-autodoc/target/singledispatch.py
+++ b/tests/roots/test-ext-autodoc/target/singledispatch.py
@@ -15,6 +15,7 @@ def func(arg, kwarg=None):
 
 
 @func.register(int)
+@func.register(float)
 def _func_int(arg, kwarg=None):
     """A function for int."""
     pass
diff --git a/tests/roots/test-ext-autodoc/target/singledispatchmethod.py b/tests/roots/test-ext-autodoc/target/singledispatchmethod.py
index b5ccbb2f0..086c7fe66 100644
--- a/tests/roots/test-ext-autodoc/target/singledispatchmethod.py
+++ b/tests/roots/test-ext-autodoc/target/singledispatchmethod.py
@@ -10,6 +10,7 @@ class Foo:
         pass
 
     @meth.register(int)
+    @meth.register(float)
     def _meth_int(self, arg, kwarg=None):
         """A method for int."""
         pass
diff --git a/tests/roots/test-root/conf.py b/tests/roots/test-root/conf.py
index 34cafa767..687445a70 100644
--- a/tests/roots/test-root/conf.py
+++ b/tests/roots/test-root/conf.py
@@ -42,7 +42,7 @@ latex_additional_files = ['svgimg.svg']
 coverage_c_path = ['special/*.h']
 coverage_c_regexes = {'function': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'}
 
-extlinks = {'issue': ('http://bugs.python.org/issue%s', 'issue '),
+extlinks = {'issue': ('http://bugs.python.org/issue%s', 'issue %s'),
             'pyurl': ('http://python.org/%s', None)}
 
 # modify tags from conf.py
diff --git a/tests/test_domain_std.py b/tests/test_domain_std.py
index 9d9e27bd0..011c82f6a 100644
--- a/tests/test_domain_std.py
+++ b/tests/test_domain_std.py
@@ -324,6 +324,23 @@ def test_cmdoption(app):
     assert domain.progoptions[('ls', '-l')] == ('index', 'cmdoption-ls-l')
 
 
+def test_cmdoption_for_None(app):
+    text = (".. program:: ls\n"
+            ".. program:: None\n"
+            "\n"
+            ".. option:: -l\n")
+    domain = app.env.get_domain('std')
+    doctree = restructuredtext.parse(app, text)
+    assert_node(doctree, (addnodes.index,
+                          [desc, ([desc_signature, ([desc_name, "-l"],
+                                                    [desc_addname, ()])],
+                                  [desc_content, ()])]))
+    assert_node(doctree[0], addnodes.index,
+                entries=[('pair', 'command line option; -l', 'cmdoption-l', '', None)])
+    assert (None, '-l') in domain.progoptions
+    assert domain.progoptions[(None, '-l')] == ('index', 'cmdoption-l')
+
+
 def test_multiple_cmdoptions(app):
     text = (".. program:: cmd\n"
             "\n"
diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py
index 2becf5de2..4c16886b3 100644
--- a/tests/test_ext_autodoc.py
+++ b/tests/test_ext_autodoc.py
@@ -736,6 +736,34 @@ def test_autodoc_undoc_members(app):
 
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_autodoc_undoc_members_for_metadata_only(app):
+    # metadata only member is not displayed
+    options = {"members": None}
+    actual = do_autodoc(app, 'module', 'target.metadata', options)
+    assert list(actual) == [
+        '',
+        '.. py:module:: target.metadata',
+        '',
+    ]
+
+    # metadata only member is displayed when undoc-member given
+    options = {"members": None,
+               "undoc-members": None}
+    actual = do_autodoc(app, 'module', 'target.metadata', options)
+    assert list(actual) == [
+        '',
+        '.. py:module:: target.metadata',
+        '',
+        '',
+        '.. py:function:: foo()',
+        '   :module: target.metadata',
+        '',
+        '   :meta metadata-only-docstring:',
+        '',
+    ]
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
 def test_autodoc_inherited_members(app):
     options = {"members": None,
                "inherited-members": None}
@@ -2080,6 +2108,7 @@ def test_singledispatch(app):
         '',
         '',
         '.. py:function:: func(arg, kwarg=None)',
+        '                 func(arg: float, kwarg=None)',
         '                 func(arg: int, kwarg=None)',
         '                 func(arg: str, kwarg=None)',
         '   :module: target.singledispatch',
@@ -2107,6 +2136,7 @@ def test_singledispatchmethod(app):
         '',
         '',
         '   .. py:method:: Foo.meth(arg, kwarg=None)',
+        '                  Foo.meth(arg: float, kwarg=None)',
         '                  Foo.meth(arg: int, kwarg=None)',
         '                  Foo.meth(arg: str, kwarg=None)',
         '      :module: target.singledispatchmethod',
@@ -2125,6 +2155,7 @@ def test_singledispatchmethod_automethod(app):
     assert list(actual) == [
         '',
         '.. py:method:: Foo.meth(arg, kwarg=None)',
+        '               Foo.meth(arg: float, kwarg=None)',
         '               Foo.meth(arg: int, kwarg=None)',
         '               Foo.meth(arg: str, kwarg=None)',
         '   :module: target.singledispatchmethod',
diff --git a/tests/test_ext_autodoc_autoclass.py b/tests/test_ext_autodoc_autoclass.py
index d879f8e14..096dc9397 100644
--- a/tests/test_ext_autodoc_autoclass.py
+++ b/tests/test_ext_autodoc_autoclass.py
@@ -264,6 +264,53 @@ def test_show_inheritance_for_subclass_of_generic_type(app):
     ]
 
 
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_class_doc_from_class(app):
+    options = {"members": None,
+               "class-doc-from": "class"}
+    actual = do_autodoc(app, 'class', 'target.autoclass_content.C', options)
+    assert list(actual) == [
+        '',
+        '.. py:class:: C()',
+        '   :module: target.autoclass_content',
+        '',
+        '   A class having __init__, no __new__',
+        '',
+    ]
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_class_doc_from_init(app):
+    options = {"members": None,
+               "class-doc-from": "init"}
+    actual = do_autodoc(app, 'class', 'target.autoclass_content.C', options)
+    assert list(actual) == [
+        '',
+        '.. py:class:: C()',
+        '   :module: target.autoclass_content',
+        '',
+        '   __init__ docstring',
+        '',
+    ]
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_class_doc_from_both(app):
+    options = {"members": None,
+               "class-doc-from": "both"}
+    actual = do_autodoc(app, 'class', 'target.autoclass_content.C', options)
+    assert list(actual) == [
+        '',
+        '.. py:class:: C()',
+        '   :module: target.autoclass_content',
+        '',
+        '   A class having __init__, no __new__',
+        '',
+        '   __init__ docstring',
+        '',
+    ]
+
+
 def test_class_alias(app):
     def autodoc_process_docstring(*args):
         """A handler always raises an error.
diff --git a/tests/test_ext_autodoc_autofunction.py b/tests/test_ext_autodoc_autofunction.py
index 615091889..ca2429b5e 100644
--- a/tests/test_ext_autodoc_autofunction.py
+++ b/tests/test_ext_autodoc_autofunction.py
@@ -119,6 +119,7 @@ def test_singledispatch(app):
     assert list(actual) == [
         '',
         '.. py:function:: func(arg, kwarg=None)',
+        '                 func(arg: float, kwarg=None)',
         '                 func(arg: int, kwarg=None)',
         '                 func(arg: str, kwarg=None)',
         '   :module: target.singledispatch',
diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py
index bc8c01fbd..04d35e335 100644
--- a/tests/test_ext_autodoc_configs.py
+++ b/tests/test_ext_autodoc_configs.py
@@ -792,27 +792,27 @@ def test_autodoc_typehints_description_for_invalid_node(app):
 def test_autodoc_type_aliases(app):
     # default
     options = {"members": None}
-    actual = do_autodoc(app, 'module', 'target.annotations', options)
+    actual = do_autodoc(app, 'module', 'target.autodoc_type_aliases', options)
     assert list(actual) == [
         '',
-        '.. py:module:: target.annotations',
+        '.. py:module:: target.autodoc_type_aliases',
         '',
         '',
         '.. py:class:: Foo()',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
         '',
         '',
         '   .. py:attribute:: Foo.attr1',
-        '      :module: target.annotations',
+        '      :module: target.autodoc_type_aliases',
         '      :type: int',
         '',
         '      docstring',
         '',
         '',
         '   .. py:attribute:: Foo.attr2',
-        '      :module: target.annotations',
+        '      :module: target.autodoc_type_aliases',
         '      :type: int',
         '',
         '      docstring',
@@ -820,26 +820,32 @@ def test_autodoc_type_aliases(app):
         '',
         '.. py:function:: mult(x: int, y: int) -> int',
         '                 mult(x: float, y: float) -> float',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
+        '',
+        '   docstring',
+        '',
+        '',
+        '.. py:function:: read(r: _io.BytesIO) -> _io.StringIO',
+        '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
         '',
         '',
         '.. py:function:: sum(x: int, y: int) -> int',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
         '',
         '',
         '.. py:data:: variable',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
         '   :type: int',
         '',
         '   docstring',
         '',
         '',
         '.. py:data:: variable2',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
         '   :type: int',
         '   :value: None',
         '',
@@ -848,28 +854,29 @@ def test_autodoc_type_aliases(app):
     ]
 
     # define aliases
-    app.config.autodoc_type_aliases = {'myint': 'myint'}
-    actual = do_autodoc(app, 'module', 'target.annotations', options)
+    app.config.autodoc_type_aliases = {'myint': 'myint',
+                                       'io.StringIO': 'my.module.StringIO'}
+    actual = do_autodoc(app, 'module', 'target.autodoc_type_aliases', options)
     assert list(actual) == [
         '',
-        '.. py:module:: target.annotations',
+        '.. py:module:: target.autodoc_type_aliases',
         '',
         '',
         '.. py:class:: Foo()',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
         '',
         '',
         '   .. py:attribute:: Foo.attr1',
-        '      :module: target.annotations',
+        '      :module: target.autodoc_type_aliases',
         '      :type: myint',
         '',
         '      docstring',
         '',
         '',
         '   .. py:attribute:: Foo.attr2',
-        '      :module: target.annotations',
+        '      :module: target.autodoc_type_aliases',
         '      :type: myint',
         '',
         '      docstring',
@@ -877,26 +884,32 @@ def test_autodoc_type_aliases(app):
         '',
         '.. py:function:: mult(x: myint, y: myint) -> myint',
         '                 mult(x: float, y: float) -> float',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
+        '',
+        '   docstring',
+        '',
+        '',
+        '.. py:function:: read(r: _io.BytesIO) -> my.module.StringIO',
+        '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
         '',
         '',
         '.. py:function:: sum(x: myint, y: myint) -> myint',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
         '',
         '',
         '.. py:data:: variable',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
         '   :type: myint',
         '',
         '   docstring',
         '',
         '',
         '.. py:data:: variable2',
-        '   :module: target.annotations',
+        '   :module: target.autodoc_type_aliases',
         '   :type: myint',
         '   :value: None',
         '',
@@ -911,10 +924,10 @@ def test_autodoc_type_aliases(app):
                     confoverrides={'autodoc_typehints': "description",
                                    'autodoc_type_aliases': {'myint': 'myint'}})
 def test_autodoc_typehints_description_and_type_aliases(app):
-    (app.srcdir / 'annotations.rst').write_text('.. autofunction:: target.annotations.sum')
+    (app.srcdir / 'autodoc_type_aliases.rst').write_text('.. autofunction:: target.autodoc_type_aliases.sum')
     app.build()
-    context = (app.outdir / 'annotations.txt').read_text()
-    assert ('target.annotations.sum(x, y)\n'
+    context = (app.outdir / 'autodoc_type_aliases.txt').read_text()
+    assert ('target.autodoc_type_aliases.sum(x, y)\n'
             '\n'
             '   docstring\n'
             '\n'
diff --git a/tests/test_ext_math.py b/tests/test_ext_math.py
index bd124c8c6..ebe2c0f38 100644
--- a/tests/test_ext_math.py
+++ b/tests/test_ext_math.py
@@ -215,11 +215,23 @@ def test_math_compat(app, status, warning):
 
 @pytest.mark.sphinx('html', testroot='ext-math',
                     confoverrides={'extensions': ['sphinx.ext.mathjax'],
-                                   'mathjax_config': {'extensions': ['tex2jax.js']}})
-def test_mathjax_config(app, status, warning):
+                                   'mathjax3_config': {'extensions': ['tex2jax.js']}})
+def test_mathjax3_config(app, status, warning):
     app.builder.build_all()
 
     content = (app.outdir / 'index.html').read_text()
+    assert MATHJAX_URL in content
+    assert ('<script>window.MathJax = {"extensions": ["tex2jax.js"]}</script>' in content)
+
+
+@pytest.mark.sphinx('html', testroot='ext-math',
+                    confoverrides={'extensions': ['sphinx.ext.mathjax'],
+                                   'mathjax2_config': {'extensions': ['tex2jax.js']}})
+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 type="text/x-mathjax-config">'
             'MathJax.Hub.Config({"extensions": ["tex2jax.js"]})'
             '</script>' in content)
diff --git a/tests/test_util_docstrings.py b/tests/test_util_docstrings.py
index 543feca2a..2d406b81c 100644
--- a/tests/test_util_docstrings.py
+++ b/tests/test_util_docstrings.py
@@ -8,31 +8,48 @@
     :license: BSD, see LICENSE for details.
 """
 
-from sphinx.util.docstrings import extract_metadata, prepare_commentdoc, prepare_docstring
+from sphinx.util.docstrings import prepare_commentdoc, prepare_docstring, separate_metadata
 
 
-def test_extract_metadata():
-    metadata = extract_metadata(":meta foo: bar\n"
-                                ":meta baz:\n")
+def test_separate_metadata():
+    # metadata only
+    text = (":meta foo: bar\n"
+            ":meta baz:\n")
+    docstring, metadata = separate_metadata(text)
+    assert docstring == ''
     assert metadata == {'foo': 'bar', 'baz': ''}
 
+    # non metadata field list item
+    text = (":meta foo: bar\n"
+            ":param baz:\n")
+    docstring, metadata = separate_metadata(text)
+    assert docstring == ':param baz:\n'
+    assert metadata == {'foo': 'bar'}
+
     # field_list like text following just after paragaph is not a field_list
-    metadata = extract_metadata("blah blah blah\n"
-                                ":meta foo: bar\n"
-                                ":meta baz:\n")
+    text = ("blah blah blah\n"
+            ":meta foo: bar\n"
+            ":meta baz:\n")
+    docstring, metadata = separate_metadata(text)
+    assert docstring == text
     assert metadata == {}
 
     # field_list like text following after blank line is a field_list
-    metadata = extract_metadata("blah blah blah\n"
-                                "\n"
-                                ":meta foo: bar\n"
-                                ":meta baz:\n")
+    text = ("blah blah blah\n"
+            "\n"
+            ":meta foo: bar\n"
+            ":meta baz:\n")
+    docstring, metadata = separate_metadata(text)
+    assert docstring == "blah blah blah\n\n"
     assert metadata == {'foo': 'bar', 'baz': ''}
 
     # non field_list item breaks field_list
-    metadata = extract_metadata(":meta foo: bar\n"
-                                "blah blah blah\n"
-                                ":meta baz:\n")
+    text = (":meta foo: bar\n"
+            "blah blah blah\n"
+            ":meta baz:\n")
+    docstring, metadata = separate_metadata(text)
+    assert docstring == ("blah blah blah\n"
+                         ":meta baz:\n")
     assert metadata == {'foo': 'bar'}
 
 
diff --git a/tests/test_util_inspect.py b/tests/test_util_inspect.py
index 7b86c6ade..fbf243ba1 100644
--- a/tests/test_util_inspect.py
+++ b/tests/test_util_inspect.py
@@ -19,7 +19,26 @@ import _testcapi
 import pytest
 
 from sphinx.util import inspect
-from sphinx.util.inspect import stringify_signature
+from sphinx.util.inspect import TypeAliasNamespace, stringify_signature
+
+
+def test_TypeAliasNamespace():
+    import logging.config
+    type_alias = TypeAliasNamespace({'logging.Filter': 'MyFilter',
+                                     'logging.Handler': 'MyHandler',
+                                     'logging.handlers.SyslogHandler': 'MySyslogHandler'})
+
+    assert type_alias['logging'].Filter == 'MyFilter'
+    assert type_alias['logging'].Handler == 'MyHandler'
+    assert type_alias['logging'].handlers.SyslogHandler == 'MySyslogHandler'
+    assert type_alias['logging'].Logger == logging.Logger
+    assert type_alias['logging'].config == logging.config
+
+    with pytest.raises(KeyError):
+        assert type_alias['log']
+
+    with pytest.raises(KeyError):
+        assert type_alias['unknown']
 
 
 def test_signature():