Close #8022: autodoc: Allow to hide the value of the variables via metadata

autodata and autoattribute directives does not show right-hand value of
the variable if its docstring contains ``:meta hide-value:`` in
info-field-list.

7 files changed, 153 insertions, 0 deletions

diff --git a/CHANGES b/CHANGES
index 9360f3473..d8e6e6faa 100644
--- a/CHANGES
+++ b/CHANGES
@@ -13,6 +13,10 @@ Deprecated
 Features added
 --------------
 
+* #8022: autodoc: autodata and autoattribute directives does not show right-hand
+  value of the variable if docstring contains ``:meta hide-value:`` in
+  info-field-list
+
 Bugs fixed
 ----------
 
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index 382d3160c..77340f494 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/doc/usage/extensions/autodoc.rst
@@ -182,6 +182,16 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
      .. versionadded:: 3.1
 
+   * autodoc considers a variable member does not have any default value if its
+     docstring contains ``:meta hide-value:`` in its :ref:`info-field-lists`.
+     Example:
+
+     .. code-block:: rst
+
+        var1 = None  #: :meta hide-value:
+
+     .. versionadded:: 3.5
+
    * Python "special" members (that is, those named like ``__special__``) will
      be included if the ``special-members`` flag option is given::
 
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index e9d7a6f00..8d9fe8e4a 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -1883,6 +1883,17 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
 
         return ret
 
+    def should_suppress_value_header(self) -> bool:
+        if super().should_suppress_value_header():
+            return True
+        else:
+            doc = self.get_doc()
+            metadata = extract_metadata('\n'.join(sum(doc, [])))
+            if 'hide-value' in metadata:
+                return True
+
+        return False
+
     def add_directive_header(self, sig: str) -> None:
         super().add_directive_header(sig)
         sourcename = self.get_sourcename()
@@ -2376,6 +2387,17 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
         return self.get_attr(self.parent or self.object, '__module__', None) \
             or self.modname
 
+    def should_suppress_value_header(self) -> bool:
+        if super().should_suppress_value_header():
+            return True
+        else:
+            doc = self.get_doc()
+            metadata = extract_metadata('\n'.join(sum(doc, [])))
+            if 'hide-value' in metadata:
+                return True
+
+        return False
+
     def add_directive_header(self, sig: str) -> None:
         super().add_directive_header(sig)
         sourcename = self.get_sourcename()
diff --git a/tests/roots/test-ext-autodoc/target/hide_value.py b/tests/roots/test-ext-autodoc/target/hide_value.py
new file mode 100644
index 000000000..1d53aabe9
--- /dev/null
+++ b/tests/roots/test-ext-autodoc/target/hide_value.py
@@ -0,0 +1,19 @@
+#: docstring
+#:
+#: :meta hide-value:
+SENTINEL1 = object()
+
+#: :meta hide-value:
+SENTINEL2 = object()
+
+
+class Foo:
+    """docstring"""
+
+    #: docstring
+    #:
+    #: :meta hide-value:
+    SENTINEL1 = object()
+
+    #: :meta hide-value:
+    SENTINEL2 = object()
diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py
index 1fa0c1d7d..39897eb7d 100644
--- a/tests/test_ext_autodoc.py
+++ b/tests/test_ext_autodoc.py
@@ -2235,3 +2235,49 @@ def test_name_mangling(app):
         '      name of Foo',
         '',
     ]
+
+
+@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_hide_value(app):
+    options = {'members': True}
+    actual = do_autodoc(app, 'module', 'target.hide_value', options)
+    assert list(actual) == [
+        '',
+        '.. py:module:: target.hide_value',
+        '',
+        '',
+        '.. py:class:: Foo()',
+        '   :module: target.hide_value',
+        '',
+        '   docstring',
+        '',
+        '',
+        '   .. py:attribute:: Foo.SENTINEL1',
+        '      :module: target.hide_value',
+        '',
+        '      docstring',
+        '',
+        '      :meta hide-value:',
+        '',
+        '',
+        '   .. py:attribute:: Foo.SENTINEL2',
+        '      :module: target.hide_value',
+        '',
+        '      :meta hide-value:',
+        '',
+        '',
+        '.. py:data:: SENTINEL1',
+        '   :module: target.hide_value',
+        '',
+        '   docstring',
+        '',
+        '   :meta hide-value:',
+        '',
+        '',
+        '.. py:data:: SENTINEL2',
+        '   :module: target.hide_value',
+        '',
+        '   :meta hide-value:',
+        '',
+    ]
diff --git a/tests/test_ext_autodoc_autoattribute.py b/tests/test_ext_autodoc_autoattribute.py
index 7f79ca332..659c8c014 100644
--- a/tests/test_ext_autodoc_autoattribute.py
+++ b/tests/test_ext_autodoc_autoattribute.py
@@ -189,3 +189,29 @@ def test_autoattribute_TypeVar(app):
         "   alias of TypeVar('T1')",
         '',
     ]
+
+
+@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_autoattribute_hide_value(app):
+    actual = do_autodoc(app, 'attribute', 'target.hide_value.Foo.SENTINEL1')
+    assert list(actual) == [
+        '',
+        '.. py:attribute:: Foo.SENTINEL1',
+        '   :module: target.hide_value',
+        '',
+        '   docstring',
+        '',
+        '   :meta hide-value:',
+        '',
+    ]
+
+    actual = do_autodoc(app, 'attribute', 'target.hide_value.Foo.SENTINEL2')
+    assert list(actual) == [
+        '',
+        '.. py:attribute:: Foo.SENTINEL2',
+        '   :module: target.hide_value',
+        '',
+        '   :meta hide-value:',
+        '',
+    ]
diff --git a/tests/test_ext_autodoc_autodata.py b/tests/test_ext_autodoc_autodata.py
index d3f63f432..c80ae5a81 100644
--- a/tests/test_ext_autodoc_autodata.py
+++ b/tests/test_ext_autodoc_autodata.py
@@ -129,3 +129,29 @@ def test_autodata_TypeVar(app):
         "   alias of TypeVar('T1')",
         '',
     ]
+
+
+@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_autodata_hide_value(app):
+    actual = do_autodoc(app, 'data', 'target.hide_value.SENTINEL1')
+    assert list(actual) == [
+        '',
+        '.. py:data:: SENTINEL1',
+        '   :module: target.hide_value',
+        '',
+        '   docstring',
+        '',
+        '   :meta hide-value:',
+        '',
+    ]
+
+    actual = do_autodoc(app, 'data', 'target.hide_value.SENTINEL2')
+    assert list(actual) == [
+        '',
+        '.. py:data:: SENTINEL2',
+        '   :module: target.hide_value',
+        '',
+        '   :meta hide-value:',
+        '',
+    ]