Finer grained control over domain ToC entries (sphinx-doc#10886)

- Implement `:nocontentsentry:` flag
- Use `:nocontentsentry:` in docs
- Add domain object table of contents configuration option

doc/usage/configuration.rst

@@ -678,6 +678,11 @@ General configuration
    :term:`object` names (for object types where a "module" of some kind is
    defined), e.g. for :rst:dir:`py:function` directives.  Default is ``True``.
 
+.. confval:: toc_object_entries
+
+  Create table of contents entries for domain objects (e.g. functions, classes,
+  attributes, etc.). Default is ``True``.
+
 .. confval:: toc_object_entries_show_parents
 
    A string that determines how domain objects (e.g. functions, classes,

doc/usage/restructuredtext/domains.rst

@@ -42,11 +42,15 @@ Basic Markup
 Most domains provide a number of :dfn:`object description directives`, used to
 describe specific objects provided by modules.  Each directive requires one or
 more signatures to provide basic information about what is being described, and
-the content should be the description.  A domain will typically keep an
-internal index of all entities to aid cross-referencing. Typically it will
-also add entries in the shown general index.
+the content should be the description.
+
+A domain will typically keep an internal index of all entities to aid
+cross-referencing.
+Typically it will also add entries in the shown general index.
 If you want to suppress the addition of an entry in the shown index, you can
 give the directive option flag ``:noindexentry:``.
+If you want to exclude the object description from the table of contents, you
+can give the directive option flag ``:nocontentsentry:``.
 If you want to typeset an object description, without even making it available
 for cross-referencing, you can give the directive option flag ``:noindex:``
 (which implies ``:noindexentry:``).
@@ -57,6 +61,10 @@ options.
    The directive option ``noindexentry`` in the Python, C, C++, and Javascript
    domains.
 
+.. versionadded:: 5.2.3
+   The directive option ``:nocontentsentry:`` in the Python, C, C++, Javascript,
+   and reStructuredText domains.
+
 An example using a Python domain directive::
 
    .. py:function:: spam(eggs)
@@ -862,15 +870,19 @@ Example::
 This will be rendered as:
 
 .. c:struct:: Data
+   :nocontentsentry:
    :noindexentry:
 
    .. c:union:: @data
+      :nocontentsentry:
       :noindexentry:
 
       .. c:var:: int a
+         :nocontentsentry:
          :noindexentry:
 
       .. c:var:: double b
+         :nocontentsentry:
          :noindexentry:
 
 Explicit ref: :c:var:`[email protected]`. Short-hand ref: :c:var:`Data.a`.
@@ -953,9 +965,11 @@ Inline Expressions and Types
    will be rendered as follows:
 
    .. c:var:: int a = 42
+      :nocontentsentry:
       :noindexentry:
 
    .. c:function:: int f(int i)
+      :nocontentsentry:
       :noindexentry:
 
    An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
@@ -1166,23 +1180,27 @@ visibility statement (``public``, ``private`` or ``protected``).
    The example are rendered as follows.
 
    .. cpp:type:: std::vector<int> MyList
-      :noindex:
+      :nocontentsentry:
+      :noindexentry:
 
       A typedef-like declaration of a type.
 
    .. cpp:type:: MyContainer::const_iterator
-      :noindex:
+      :nocontentsentry:
+      :noindexentry:
 
       Declaration of a type alias with unspecified type.
 
    .. cpp:type:: MyType = std::unordered_map<int, std::string>
-      :noindex:
+      :nocontentsentry:
+      :noindexentry:
 
       Declaration of a type alias.
 
    .. cpp:type:: template<typename T> \
                  MyContainer = std::vector<T>
-      :noindex:
+      :nocontentsentry:
+      :noindexentry:
 
 .. rst:directive:: .. cpp:enum:: unscoped enum declaration
                    .. cpp:enum-struct:: scoped enum declaration
@@ -1277,7 +1295,7 @@ Options
 
 Some directives support options:
 
-- ``:noindexentry:``, see :ref:`basic-domain-markup`.
+- ``:noindexentry:`` and ``:nocontentsentry:``, see :ref:`basic-domain-markup`.
 - ``:tparam-line-spec:``, for templated declarations.
   If specified, each template parameter will be rendered on a separate line.
 
@@ -1309,15 +1327,19 @@ Example::
 This will be rendered as:
 
 .. cpp:class:: Data
+   :nocontentsentry:
    :noindexentry:
 
    .. cpp:union:: @data
+      :nocontentsentry:
       :noindexentry:
 
       .. cpp:var:: int a
+         :nocontentsentry:
          :noindexentry:
 
       .. cpp:var:: double b
+         :nocontentsentry:
          :noindexentry:
 
 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
@@ -1424,11 +1446,13 @@ introduction` instead of a template parameter list::
 They are rendered as follows.
 
 .. cpp:function:: std::Iterator{It} void advance(It &it)
+   :nocontentsentry:
    :noindexentry:
 
    A function template with a template parameter constrained to be an Iterator.
 
 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
+   :nocontentsentry:
    :noindexentry:
 
    A class template with a template parameter constrained to be
@@ -1459,9 +1483,11 @@ Inline Expressions and Types
    will be rendered as follows:
 
    .. cpp:var:: int a = 42
+      :nocontentsentry:
       :noindexentry:
 
    .. cpp:function:: int f(int i)
+      :nocontentsentry:
       :noindexentry:
 
    An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).

sphinx/config.py

@@ -106,6 +106,7 @@ class Config:
         'default_role': (None, 'env', [str]),
         'add_function_parentheses': (True, 'env', []),
         'add_module_names': (True, 'env', []),
+        'toc_object_entries': (True, 'env', [bool]),
         'toc_object_entries_show_parents': ('domain', 'env',
                                             ENUM('domain', 'all', 'hide')),
         'trim_footnote_reference_space': (False, 'env', []),

sphinx/directives/__init__.py

@@ -51,6 +51,8 @@ class ObjectDescription(SphinxDirective, Generic[T]):
     final_argument_whitespace = True
     option_spec: OptionSpec = {
         'noindex': directives.flag,
+        'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
     }
 
     # types of doc fields that this directive handles, see sphinx.util.docfields
@@ -211,6 +213,7 @@ def run(self) -> List[Node]:
         node['objtype'] = node['desctype'] = self.objtype
         node['noindex'] = noindex = ('noindex' in self.options)
         node['noindexentry'] = ('noindexentry' in self.options)
+        node['nocontentsentry'] = ('nocontentsentry' in self.options)
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
@@ -236,8 +239,12 @@ def run(self) -> List[Node]:
             finally:
                 # Private attributes for ToC generation. Will be modified or removed
                 # without notice.
-                signode['_toc_parts'] = self._object_hierarchy_parts(signode)
-                signode['_toc_name'] = self._toc_entry_name(signode)
+                if self.env.app.config.toc_object_entries:
+                    signode['_toc_parts'] = self._object_hierarchy_parts(signode)
+                    signode['_toc_name'] = self._toc_entry_name(signode)
+                else:
+                    signode['_toc_parts'] = ()
+                    signode['_toc_name'] = ''
             if name not in self.names:
                 self.names.append(name)
                 if not noindex:

sphinx/domains/c.py

@@ -3142,8 +3142,8 @@ class CObject(ObjectDescription[ASTDeclaration]):
     """
 
     option_spec: OptionSpec = {
-        'noindex': directives.flag,
         'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
     }
 
     def _add_enumerator_to_parent(self, ast: ASTDeclaration) -> None:

sphinx/domains/cpp.py

@@ -7186,8 +7186,8 @@ class CPPObject(ObjectDescription[ASTDeclaration]):
     ]
 
     option_spec: OptionSpec = {
-        'noindex': directives.flag,
         'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
         'tparam-line-spec': directives.flag,
     }
 

sphinx/domains/javascript.py

@@ -40,6 +40,7 @@ class JSObject(ObjectDescription[Tuple[str, str]]):
     option_spec: OptionSpec = {
         'noindex': directives.flag,
         'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
     }
 
     def get_display_prefix(self) -> List[Node]:
@@ -284,7 +285,8 @@ class JSModule(SphinxDirective):
     optional_arguments = 0
     final_argument_whitespace = False
     option_spec: OptionSpec = {
-        'noindex': directives.flag
+        'noindex': directives.flag,
+        'nocontentsentry': directives.flag,
     }
 
     def run(self) -> List[Node]:

sphinx/domains/python.py

@@ -427,6 +427,7 @@ class PyObject(ObjectDescription[Tuple[str, str]]):
     option_spec: OptionSpec = {
         'noindex': directives.flag,
         'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
         'module': directives.unchanged,
         'canonical': directives.unchanged,
         'annotation': directives.unchanged,
@@ -1008,6 +1009,7 @@ class PyModule(SphinxDirective):
         'platform': lambda x: x,
         'synopsis': lambda x: x,
         'noindex': directives.flag,
+        'nocontentsentry': directives.flag,
         'deprecated': directives.flag,
     }
 

sphinx/domains/rst.py

@@ -31,6 +31,7 @@ class ReSTMarkup(ObjectDescription[str]):
     option_spec: OptionSpec = {
         'noindex': directives.flag,
         'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
     }
 
     def add_target_and_index(self, name: str, sig: str, signode: desc_signature) -> None:

sphinx/environment/collectors/toctree.py

@@ -112,9 +112,12 @@ def build_toc(
                                 # Skip if no name set
                                 if not sig_node.get('_toc_name', ''):
                                     continue
+                                # Skip if explicitly disabled
+                                if sig_node.parent.get('nocontentsentry'):
+                                    continue
                                 # Skip entries with no ID (e.g. with :noindex: set)
                                 ids = sig_node['ids']
-                                if not ids or sig_node.parent.get('noindexentry'):
+                                if not ids:
                                     continue
 
                                 anchorname = _make_anchor_name(ids, numentries)