From 4020d965b4cda4c9e45cba6988a5f0066a2d8634 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Fri, 30 Sep 2022 10:31:58 +0100 Subject: [PATCH] Finer grained control over domain ToC entries (#10886) - Implement `:nocontentsentry:` flag - Use `:nocontentsentry:` in docs - Add domain object table of contents configuration option --- doc/usage/configuration.rst | 5 +++ doc/usage/restructuredtext/domains.rst | 42 +++++++++++++++++++----- sphinx/config.py | 1 + sphinx/directives/__init__.py | 11 +++++-- sphinx/domains/c.py | 2 +- sphinx/domains/cpp.py | 2 +- sphinx/domains/javascript.py | 4 ++- sphinx/domains/python.py | 2 ++ sphinx/domains/rst.py | 1 + sphinx/environment/collectors/toctree.py | 5 ++- 10 files changed, 61 insertions(+), 14 deletions(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 5866b0e2977..906827ff32e 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 ce146fc2301..cc0713b9fd1 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 45df6bb0057..2906a328578 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 b6838a6fd7a..e59cb1295d8 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 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..8f49fcaa008 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 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)