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

add more extendable options and tests

Browse Source
This commit is contained in:
pbudzyns
2021-01-25 12:54:08 +01:00
parent 6f78f0b164
commit 0a85b4148e
2 changed files with 184 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
sphinx/ext/autodoc/directive.py
View File

@@ -37,6 +37,8 @@ AUTODOC_DEFAULT_OPTIONS = ['members', 'undoc-members', 'inherited-members',
'ignore-module-all', 'exclude-members', 'member-order',
'imported-members']
AUTODOC_EXTENDABLE_OPTIONS = ['members', 'special-members', 'exclude-members']
class DummyOptionSpec(dict):
"""An option_spec allows any options."""
@@ -84,10 +86,12 @@ def process_documenter_options(documenter: "Type[Documenter]", config: Config, o
else:
negated = options.pop('no-' + name, True) is None
if name in config.autodoc_default_options and not negated:
if name == "exclude-members":
if config.autodoc_default_options[name]:
options[name] = config.autodoc_default_options[name] \
+ options.get(name, '')
if name in options:
# take value from options if present or extend it with autodoc_default_options if necessary
if name in AUTODOC_EXTENDABLE_OPTIONS:
if options[name] is not None and options[name].startswith('+'):
options[name] = ','.join([config.autodoc_default_options[name],
options[name][1:]])
else:
options[name] = config.autodoc_default_options[name]

176
tests/test_ext_autodoc.py
View File

@@ -578,6 +578,36 @@ def test_autodoc_members(app):
' .. py:method:: Base.inheritedstaticmeth(cls)'
]
# ALL-members override autodoc_default_options
options = {"members": None}
app.config.autodoc_default_options["members"] = "inheritedstaticmeth"
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:method:: Base.inheritedclassmeth()',
' .. py:method:: Base.inheritedmeth()',
' .. py:method:: Base.inheritedstaticmeth(cls)'
]
# members override autodoc_default_options
options = {"members": "inheritedmeth"}
app.config.autodoc_default_options["members"] = "inheritedstaticmeth"
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:method:: Base.inheritedmeth()',
]
# members extends autodoc_default_options
options = {"members": "+inheritedmeth"}
app.config.autodoc_default_options["members"] = "inheritedstaticmeth"
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:method:: Base.inheritedmeth()',
' .. py:method:: Base.inheritedstaticmeth(cls)'
]
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_autodoc_exclude_members(app):
@@ -597,6 +627,48 @@ def test_autodoc_exclude_members(app):
'.. py:class:: Base()',
]
# exclude-members overrides autodoc_default_options
options = {"members": None,
"exclude-members": "inheritedmeth"}
app.config.autodoc_default_options["exclude-members"] = "inheritedstaticmeth"
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:method:: Base.inheritedclassmeth()',
' .. py:method:: Base.inheritedstaticmeth(cls)'
]
# exclude-members extends autodoc_default_options
options = {"members": None,
"exclude-members": "+inheritedmeth"}
app.config.autodoc_default_options["exclude-members"] = "inheritedstaticmeth"
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:method:: Base.inheritedclassmeth()',
]
# no exclude-members causes use autodoc_default_options
options = {"members": None}
app.config.autodoc_default_options["exclude-members"] = "inheritedstaticmeth,inheritedmeth"
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:method:: Base.inheritedclassmeth()',
]
# empty exclude-members cancels autodoc_default_options
options = {"members": None,
"exclude-members": None}
app.config.autodoc_default_options["exclude-members"] = "inheritedstaticmeth,inheritedmeth"
actual = do_autodoc(app, 'class', 'target.inheritance.Base', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Base()',
' .. py:method:: Base.inheritedclassmeth()',
' .. py:method:: Base.inheritedmeth()',
' .. py:method:: Base.inheritedstaticmeth(cls)'
]
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_autodoc_undoc_members(app):
@@ -621,6 +693,48 @@ def test_autodoc_undoc_members(app):
' .. py:method:: Class.undocmeth()'
]
# use autodoc_default_options
options = {"members": None}
app.config.autodoc_default_options["undoc-members"] = None
actual = do_autodoc(app, 'class', 'target.Class', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Class(arg)',
' .. py:attribute:: Class.attr',
' .. py:attribute:: Class.docattr',
' .. py:method:: Class.excludemeth()',
' .. py:attribute:: Class.inst_attr_comment',
' .. py:attribute:: Class.inst_attr_inline',
' .. py:attribute:: Class.inst_attr_string',
' .. py:attribute:: Class.mdocattr',
' .. py:method:: Class.meth()',
' .. py:method:: Class.moore(a, e, f) -> happiness',
' .. py:method:: Class.roger(a, *, b=2, c=3, d=4, e=5, f=6)',
' .. py:attribute:: Class.skipattr',
' .. py:method:: Class.skipmeth()',
' .. py:attribute:: Class.udocattr',
' .. py:method:: Class.undocmeth()'
]
# options negation work check
options = {"members": None,
"no-undoc-members": None}
app.config.autodoc_default_options["undoc-members"] = None
actual = do_autodoc(app, 'class', 'target.Class', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Class(arg)',
' .. py:attribute:: Class.attr',
' .. py:attribute:: Class.docattr',
' .. py:method:: Class.excludemeth()',
' .. py:attribute:: Class.inst_attr_comment',
' .. py:attribute:: Class.inst_attr_inline',
' .. py:attribute:: Class.inst_attr_string',
' .. py:attribute:: Class.mdocattr',
' .. py:method:: Class.meth()',
' .. py:method:: Class.moore(a, e, f) -> happiness',
' .. py:method:: Class.skipmeth()',
' .. py:attribute:: Class.udocattr',
]
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_autodoc_inherited_members(app):
@@ -721,6 +835,68 @@ def test_autodoc_special_members(app):
' .. py:method:: Class.undocmeth()'
]
# specific special methods from autodoc_default_options
options = {"undoc-members": None}
app.config.autodoc_default_options["special-members"] = "__special2__"
actual = do_autodoc(app, 'class', 'target.Class', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Class(arg)',
' .. py:method:: Class.__special2__()',
]
# specific special methods option with autodoc_default_options
options = {"undoc-members": None,
"special-members": "__init__,__special1__"}
app.config.autodoc_default_options["special-members"] = "__special2__"
actual = do_autodoc(app, 'class', 'target.Class', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Class(arg)',
' .. py:method:: Class.__init__(arg)',
' .. py:method:: Class.__special1__()',
]
# specific special methods merge with autodoc_default_options
options = {"undoc-members": None,
"special-members": "+__init__,__special1__"}
app.config.autodoc_default_options["special-members"] = "__special2__"
actual = do_autodoc(app, 'class', 'target.Class', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Class(arg)',
' .. py:method:: Class.__init__(arg)',
' .. py:method:: Class.__special1__()',
' .. py:method:: Class.__special2__()',
]
# all special methods with autodoc_default_options
options = {"members": None,
"undoc-members": None,
"special-members": None}
app.config.autodoc_default_options["special-members"] = "__special1__"
actual = do_autodoc(app, 'class', 'target.Class', options)
assert list(filter(lambda l: '::' in l, actual)) == [
'.. py:class:: Class(arg)',
' .. py:attribute:: Class.__dict__',
' .. py:method:: Class.__init__(arg)',
' .. py:attribute:: Class.__module__',
' .. py:method:: Class.__special1__()',
' .. py:method:: Class.__special2__()',
' .. py:attribute:: Class.__weakref__',
' .. py:attribute:: Class.attr',
' .. py:attribute:: Class.docattr',
' .. py:method:: Class.excludemeth()',
' .. py:attribute:: Class.inst_attr_comment',
' .. py:attribute:: Class.inst_attr_inline',
' .. py:attribute:: Class.inst_attr_string',
' .. py:attribute:: Class.mdocattr',
' .. py:method:: Class.meth()',
' .. py:method:: Class.moore(a, e, f) -> happiness',
' .. py:method:: Class.roger(a, *, b=2, c=3, d=4, e=5, f=6)',
' .. py:attribute:: Class.skipattr',
' .. py:method:: Class.skipmeth()',
' .. py:attribute:: Class.udocattr',
' .. py:method:: Class.undocmeth()'
]
@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_autodoc_ignore_module_all(app):