diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index b9c0032de8b..0fae673346a 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) @@ -1277,7 +1285,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. diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index b6838a6fd7a..2c8bdcdc51a 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']) diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py index 61e3c4e1774..e12eabfdc3b 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 b448449b707..b509b34893e 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 b78dfd30e0e..391cebf3391 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 bd507a21c85..8e0e3cca9fb 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 fc7f2e551bf..a8d5057eb9e 100644 --- a/sphinx/domains/rst.py +++ b/sphinx/domains/rst.py @@ -29,8 +29,8 @@ class ReSTMarkup(ObjectDescription[str]): Description of generic reST markup. """ 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 68c730504ae..d923f097cf0 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)