diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 5866b0e297..906827ff32 100644 --- a/doc/usage/configuration.rst +++ b/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, diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index 397416a890..cf9867779e 100644 --- a/doc/usage/restructuredtext/domains.rst +++ b/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:`Data.@data.a`. 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 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 - :noindex: + :nocontentsentry: + :noindexentry: Declaration of a type alias. .. cpp:type:: template \ MyContainer = std::vector - :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)`). diff --git a/sphinx/config.py b/sphinx/config.py index 45df6bb005..2906a32857 100644 --- a/sphinx/config.py +++ b/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', []), diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index b6838a6fd7..e59cb1295d 100644 --- a/sphinx/directives/__init__.py +++ b/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: diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py index 61e3c4e177..e12eabfdc3 100644 --- a/sphinx/domains/c.py +++ b/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: diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py index b448449b70..b509b34893 100644 --- a/sphinx/domains/cpp.py +++ b/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, } diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py index b78dfd30e0..391cebf339 100644 --- a/sphinx/domains/javascript.py +++ b/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]: diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index bd507a21c8..8e0e3cca9f 100644 --- a/sphinx/domains/python.py +++ b/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, } diff --git a/sphinx/domains/rst.py b/sphinx/domains/rst.py index fc7f2e551b..8f49fcaa00 100644 --- a/sphinx/domains/rst.py +++ b/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: diff --git a/sphinx/environment/collectors/toctree.py b/sphinx/environment/collectors/toctree.py index 68c730504a..d923f097cf 100644 --- a/sphinx/environment/collectors/toctree.py +++ b/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)