Merge pull request #8424 from tk0miya/8222_novalue

autodoc: Add :no-value: option to autoattribute and autodata to suppress the default value of the variable

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

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::
 

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)

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üß',
+        '',
+    ]

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',
+        '',
+    ]