Initial implementation of 'hidden' option for domain directives

Fixes sphinx-doc#9662
jakobandersen · Sep 25, 2021 · 823fdbd · 823fdbd
1 parent 699d03f
commit 823fdbd
Show file tree

Hide file tree

Showing 6 changed files with 43 additions and 9 deletions.
diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py
@@ -60,6 +60,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
     final_argument_whitespace = True
     option_spec: OptionSpec = {
         'noindex': directives.flag,
+        'hidden': directives.flag,
     }
 
     # types of doc fields that this directive handles, see sphinx.util.docfields
@@ -170,6 +171,7 @@ def run(self) -> List[Node]:
         # 'desctype' is a backwards compatible attribute
         node['objtype'] = node['desctype'] = self.objtype
         node['noindex'] = noindex = ('noindex' in self.options)
+        node['hidden'] = 'hidden' in self.options
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])

diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py
@@ -3140,9 +3140,11 @@ class CObject(ObjectDescription[ASTDeclaration]):
               names=('rtype',)),
     ]
 
-    option_spec: OptionSpec = {
+    option_spec: OptionSpec = ObjectDescription.option_spec.copy()
+    option_spec.update({
         'noindexentry': directives.flag,
-    }
+    })
+    del option_spec['noindex']  # is in ObjectDescription but doesn't make sense here
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
         assert ast.objectType == 'enumerator'

diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py
@@ -6948,10 +6948,12 @@ class CPPObject(ObjectDescription[ASTDeclaration]):
               names=('returns', 'return')),
     ]
 
-    option_spec: OptionSpec = {
+    option_spec: OptionSpec = ObjectDescription.option_spec.copy()
+    option_spec.update({
         'noindexentry': directives.flag,
         'tparam-line-spec': directives.flag,
-    }
+    })
+    del option_spec['noindex']  # is in ObjectDescription but doesn't make sense here
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:
         assert ast.objectType == 'enumerator'

diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py
@@ -48,10 +48,11 @@ class JSObject(ObjectDescription[Tuple[str, str]]):
     #: based on directive nesting
     allow_nesting = False
 
-    option_spec: OptionSpec = {
+    option_spec: OptionSpec = ObjectDescription.option_spec.copy()
+    option_spec.update({
         'noindex': directives.flag,
         'noindexentry': directives.flag,
-    }
+    })
 
     def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]:
         """Breaks down construct signatures

diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
@@ -389,13 +389,13 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
     :cvar allow_nesting: Class is an object that allows for nested namespaces
     :vartype allow_nesting: bool
     """
-    option_spec: OptionSpec = {
-        'noindex': directives.flag,
+    option_spec: OptionSpec = ObjectDescription.option_spec.copy()
+    option_spec.update({
         'noindexentry': directives.flag,
         'module': directives.unchanged,
         'canonical': directives.unchanged,
         'annotation': directives.unchanged,
-    }
+    })
 
     doc_field_types = [
         PyTypedField('parameter', label=_('Parameters'),

diff --git a/sphinx/transforms/post_transforms/__init__.py b/sphinx/transforms/post_transforms/__init__.py
@@ -267,11 +267,38 @@ def run(self, **kwargs: Any) -> None:
                 node['classes'].append(node.parent['domain'])
 
 
+class HideHiddenDesc(SphinxPostTransform):
+    """Change all desc nodes to a node just with all ids in the subtree."""
+    default_priority = 200
+
+    def run(self, **kwargs: Any) -> None:
+        for node in self.document.traverse(addnodes.desc):
+            if not node.get('hidden'):
+                continue
+
+            def collectIds(node, ids):
+                if not isinstance(node, nodes.Element):
+                    return
+                theseIds = node.get('ids')
+                if theseIds:
+                    ids.extend(theseIds)
+                for c in node.children:
+                    collectIds(c, ids)
+
+            ids: List[str] = []
+            collectIds(node, ids)
+            newNode = nodes.inline()
+            newNode['ids'] = ids
+            node.replace_self(newNode)
+            node['classes'] = []  # replace_self seems to copy attributes
+
+
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_post_transform(ReferencesResolver)
     app.add_post_transform(OnlyNodeTransform)
     app.add_post_transform(SigElementFallbackTransform)
     app.add_post_transform(PropagateDescDomain)
+    app.add_post_transform(HideHiddenDesc)
 
     return {
         'version': 'builtin',