IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #10428 from tk0miya/10258_autosummary

Browse Source 
Recognize a documented attribute of a module as non-imported
This commit is contained in:
Takeshi KOMIYA
2022-05-07 22:29:34 +09:00
committed by GitHub
parent 3bc1a33892 06e5c036b7
commit ba0d5a2666
5 changed files with 31 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGES
View File

@@ -70,6 +70,8 @@ Features added
* #9792: autodoc: Add new option for ``autodoc_typehints_description_target`` to
include undocumented return values but not undocumented parameters.
* #10285: autodoc: singledispatch functions having typehints are not documented
* #10258: autosummary: Recognize a documented attribute of a module as
non-imported
* #10028: Removed internal usages of JavaScript frameworks (jQuery and
underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to
EMCAScript 2018.

6
sphinx/ext/autosummary/generate.py
View File

@@ -155,6 +155,8 @@ class ModuleScanner:
def scan(self, imported_members: bool) -> List[str]:
members = []
analyzer = ModuleAnalyzer.for_module(self.object.__name__)
attr_docs = analyzer.find_attr_docs()
for name in members_of(self.object, self.app.config):
try:
value = safe_getattr(self.object, name)
@@ -166,7 +168,9 @@ class ModuleScanner:
continue
try:
if inspect.ismodule(value):
if ('', name) in attr_docs:
imported = False
elif inspect.ismodule(value):
imported = True
elif safe_getattr(value, '__module__') != self.object.__name__:
imported = True

2
tests/roots/test-ext-autosummary/autosummary_class_module.py Normal file
View File

@@ -0,0 +1,2 @@
class Class():
pass

6
tests/roots/test-ext-autosummary/autosummary_dummy_module.py
View File

@@ -1,6 +1,8 @@
from os import path # NOQA
from typing import Union
from autosummary_class_module import Class
__all__ = [
"CONSTANT1",
"Exc",
@@ -60,3 +62,7 @@ class _Exc(Exception):
qux = 2
#: a module-level attribute that has been excluded from __all__
quuz = 2
considered_as_imported = Class()
non_imported_member = Class()
""" This attribute has a docstring, so it is recognized as a not-imported member """

28
tests/test_ext_autosummary.py
View File

@@ -210,15 +210,15 @@ def test_autosummary_generate_content_for_module(app):
assert context['members'] == ['CONSTANT1', 'CONSTANT2', 'Exc', 'Foo', '_Baz', '_Exc',
'__all__', '__builtins__', '__cached__', '__doc__',
'__file__', '__name__', '__package__', '_quux', 'bar',
'quuz', 'qux']
'non_imported_member', 'quuz', 'qux']
assert context['functions'] == ['bar']
assert context['all_functions'] == ['_quux', 'bar']
assert context['classes'] == ['Foo']
assert context['all_classes'] == ['Foo', '_Baz']
assert context['exceptions'] == ['Exc']
assert context['all_exceptions'] == ['Exc', '_Exc']
assert context['attributes'] == ['CONSTANT1', 'qux', 'quuz']
assert context['all_attributes'] == ['CONSTANT1', 'qux', 'quuz']
assert context['attributes'] == ['CONSTANT1', 'qux', 'quuz', 'non_imported_member']
assert context['all_attributes'] == ['CONSTANT1', 'qux', 'quuz', 'non_imported_member']
assert context['fullname'] == 'autosummary_dummy_module'
assert context['module'] == 'autosummary_dummy_module'
assert context['objname'] == ''
@@ -268,7 +268,8 @@ def test_autosummary_generate_content_for_module_skipped(app):
context = template.render.call_args[0][1]
assert context['members'] == ['CONSTANT1', 'CONSTANT2', '_Baz', '_Exc', '__all__',
'__builtins__', '__cached__', '__doc__', '__file__',
'__name__', '__package__', '_quux', 'quuz', 'qux']
'__name__', '__package__', '_quux', 'non_imported_member',
'quuz', 'qux']
assert context['functions'] == []
assert context['classes'] == []
assert context['exceptions'] == []
@@ -284,18 +285,20 @@ def test_autosummary_generate_content_for_module_imported_members(app):
assert template.render.call_args[0][0] == 'module'
context = template.render.call_args[0][1]
assert context['members'] == ['CONSTANT1', 'CONSTANT2', 'Exc', 'Foo', 'Union', '_Baz',
'_Exc', '__all__', '__builtins__', '__cached__', '__doc__',
'__file__', '__loader__', '__name__', '__package__',
'__spec__', '_quux', 'bar', 'path', 'quuz', 'qux']
assert context['members'] == ['CONSTANT1', 'CONSTANT2', 'Class', 'Exc', 'Foo', 'Union',
'_Baz', '_Exc', '__all__', '__builtins__', '__cached__',
'__doc__', '__file__', '__loader__', '__name__',
'__package__', '__spec__', '_quux', 'bar',
'considered_as_imported', 'non_imported_member', 'path',
'quuz', 'qux']
assert context['functions'] == ['bar']
assert context['all_functions'] == ['_quux', 'bar']
assert context['classes'] == ['Foo']
assert context['all_classes'] == ['Foo', '_Baz']
assert context['classes'] == ['Class', 'Foo']
assert context['all_classes'] == ['Class', 'Foo', '_Baz']
assert context['exceptions'] == ['Exc']
assert context['all_exceptions'] == ['Exc', '_Exc']
assert context['attributes'] == ['CONSTANT1', 'qux', 'quuz']
assert context['all_attributes'] == ['CONSTANT1', 'qux', 'quuz']
assert context['attributes'] == ['CONSTANT1', 'qux', 'quuz', 'non_imported_member']
assert context['all_attributes'] == ['CONSTANT1', 'qux', 'quuz', 'non_imported_member']
assert context['fullname'] == 'autosummary_dummy_module'
assert context['module'] == 'autosummary_dummy_module'
assert context['objname'] == ''
@@ -343,6 +346,7 @@ def test_autosummary_generate(app, status, warning):
' CONSTANT1\n'
' qux\n'
' quuz\n'
' non_imported_member\n'
' \n' in module)
Foo = (app.srcdir / 'generated' / 'autosummary_dummy_module.Foo.rst').read_text(encoding='utf8')