summaryrefslogtreecommitdiff
path: root/tests
diff options
context:
space:
mode:
Diffstat (limited to 'tests')
-rw-r--r--tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py (renamed from tests/roots/test-ext-autodoc/target/annotations.py)5
-rw-r--r--tests/roots/test-ext-autodoc/target/metadata.py2
-rw-r--r--tests/roots/test-ext-autodoc/target/singledispatch.py1
-rw-r--r--tests/roots/test-ext-autodoc/target/singledispatchmethod.py1
-rw-r--r--tests/roots/test-root/conf.py2
-rw-r--r--tests/test_domain_std.py17
-rw-r--r--tests/test_ext_autodoc.py31
-rw-r--r--tests/test_ext_autodoc_autoclass.py47
-rw-r--r--tests/test_ext_autodoc_autofunction.py1
-rw-r--r--tests/test_ext_autodoc_configs.py57
-rw-r--r--tests/test_ext_math.py16
-rw-r--r--tests/test_util_docstrings.py45
-rw-r--r--tests/test_util_inspect.py21
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():
View Lorry Controller Status