diff --git a/CHANGES b/CHANGES index 6dd7a74208..b6bfa0e936 100644 --- a/CHANGES +++ b/CHANGES @@ -27,6 +27,8 @@ Features added * autodoc: Add ``Documenter.config`` as a shortcut to access the config object * autodoc: Add Optional[t] to annotation of function and method if a default value equal to None is set. +* #8209: autodoc: Add ``:no-value:`` option to :rst:dir:`autoattribute` and + :rst:dir:`autodata` directive to suppress the default value of the variable * #6914: Add a new event :event:`warn-missing-reference` to custom warning messages when failed to resolve a cross-reference * #6914: Emit a detailed warning when failed to resolve a ``:ref:`` reference diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst index 2d8a216c0d..382d3160cc 100644 --- a/doc/usage/extensions/autodoc.rst +++ b/doc/usage/extensions/autodoc.rst @@ -326,6 +326,15 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, By default, without ``annotation`` option, Sphinx tries to obtain the value of the variable and print it after the name. + The ``no-value`` option can be used instead of a blank ``annotation`` to show the + type hint but not the value:: + + .. autodata:: CD_DRIVE + :no-value: + + If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no + effect. + For module data members and class attributes, documentation can either be put into a comment with special formatting (using a ``#:`` to start the comment instead of just ``#``), or in a docstring *after* the definition. Comments @@ -365,6 +374,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, option. .. versionchanged:: 2.0 :rst:dir:`autodecorator` added. + .. versionchanged:: 3.4 + :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value`` + option. .. note:: diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 665927268e..1bd49fc38c 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -1690,6 +1690,7 @@ class DataDocumenter(ModuleLevelDocumenter): priority = -10 option_spec = dict(ModuleLevelDocumenter.option_spec) option_spec["annotation"] = annotation_option + option_spec["no-value"] = bool_option @classmethod def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any @@ -1712,7 +1713,7 @@ class DataDocumenter(ModuleLevelDocumenter): sourcename) try: - if self.object is UNINITIALIZED_ATTR: + if self.object is UNINITIALIZED_ATTR or self.options.no_value: pass else: objrepr = object_description(self.object) @@ -2008,6 +2009,7 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): member_order = 60 option_spec = dict(ModuleLevelDocumenter.option_spec) option_spec["annotation"] = annotation_option + option_spec["no-value"] = bool_option # must be higher than the MethodDocumenter, else it will recognize # some non-data descriptors as methods @@ -2092,7 +2094,7 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): # data descriptors do not have useful values if not self._datadescriptor: try: - if self.object is INSTANCEATTR: + if self.object is INSTANCEATTR or self.options.no_value: pass else: objrepr = object_description(self.object) diff --git a/tests/test_ext_autodoc_autoattribute.py b/tests/test_ext_autodoc_autoattribute.py new file mode 100644 index 0000000000..ca74f9aeb6 --- /dev/null +++ b/tests/test_ext_autodoc_autoattribute.py @@ -0,0 +1,41 @@ +""" + test_ext_autodoc_autoattribute + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Test the autodoc extension. This tests mainly the Documenters; the auto + directives are tested in a test source file translated by test_build. + + :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import pytest +from test_ext_autodoc import do_autodoc + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autoattribute(app): + actual = do_autodoc(app, 'attribute', 'target.Class.attr') + assert list(actual) == [ + '', + '.. py:attribute:: Class.attr', + ' :module: target', + " :value: 'bar'", + '', + ' should be documented -- süß', + '', + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autoattribute_novalue(app): + options = {'no-value': True} + actual = do_autodoc(app, 'attribute', 'target.Class.attr', options) + assert list(actual) == [ + '', + '.. py:attribute:: Class.attr', + ' :module: target', + '', + ' should be documented -- süß', + '', + ] diff --git a/tests/test_ext_autodoc_autodata.py b/tests/test_ext_autodoc_autodata.py new file mode 100644 index 0000000000..7e4471db9e --- /dev/null +++ b/tests/test_ext_autodoc_autodata.py @@ -0,0 +1,41 @@ +""" + test_ext_autodoc_autodata + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + Test the autodoc extension. This tests mainly the Documenters; the auto + directives are tested in a test source file translated by test_build. + + :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import pytest +from test_ext_autodoc import do_autodoc + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autodata(app): + actual = do_autodoc(app, 'data', 'target.integer') + assert list(actual) == [ + '', + '.. py:data:: integer', + ' :module: target', + ' :value: 1', + '', + ' documentation for the integer', + '', + ] + + +@pytest.mark.sphinx('html', testroot='ext-autodoc') +def test_autodata_novalue(app): + options = {'no-value': True} + actual = do_autodoc(app, 'data', 'target.integer', options) + assert list(actual) == [ + '', + '.. py:data:: integer', + ' :module: target', + '', + ' documentation for the integer', + '', + ]