From 3fbe4ac74c37a359f7329650b262a233ca769752 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 29 Sep 2022 19:24:04 +0100 Subject: [PATCH] Implement `nocontentsentry` flag --- doc/usage/restructuredtext/domains.rst | 44 ++++++++++++++---------- sphinx/directives/__init__.py | 3 ++ sphinx/domains/c.py | 2 +- sphinx/domains/cpp.py | 2 +- sphinx/domains/javascript.py | 4 ++- sphinx/domains/python.py | 2 ++ sphinx/domains/rst.py | 2 +- sphinx/environment/collectors/toctree.py | 5 ++- 8 files changed, 41 insertions(+), 23 deletions(-) diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst index b9c0032de8b..1c78ec008d0 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) @@ -523,7 +531,7 @@ For functions with optional parameters that don't have default values argument support), you can use brackets to specify the optional parts: .. py:function:: compile(source[, filename[, symbol]]) - :noindex: + :nocontentsentry: It is customary to put the opening bracket before the comma. @@ -580,7 +588,7 @@ explained by an example:: This will render like this: .. py:function:: send_message(sender, recipient, message_body, [priority=1]) - :noindex: + :nocontentsentry: Send a message to a recipient @@ -1166,23 +1174,23 @@ visibility statement (``public``, ``private`` or ``protected``). The example are rendered as follows. .. cpp:type:: std::vector MyList - :noindex: + :nocontentsentry: A typedef-like declaration of a type. .. cpp:type:: MyContainer::const_iterator - :noindex: + :nocontentsentry: Declaration of a type alias with unspecified type. .. cpp:type:: MyType = std::unordered_map - :noindex: + :nocontentsentry: Declaration of a type alias. .. cpp:type:: template \ MyContainer = std::vector - :noindex: + :nocontentsentry: .. rst:directive:: .. cpp:enum:: unscoped enum declaration .. cpp:enum-struct:: scoped enum declaration @@ -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. @@ -1878,7 +1886,7 @@ The JavaScript domain (name **js**) provides the following directives: This is rendered as: .. js:function:: $.getJSON(href, callback[, errback]) - :noindex: + :nocontentsentry: :param string href: An URI to the location of the resource. :param callback: Gets called with the object. @@ -1908,7 +1916,7 @@ The JavaScript domain (name **js**) provides the following directives: This is rendered as: .. js:class:: MyAnimal(name[, age]) - :noindex: + :nocontentsentry: :param string name: The name of the animal :param number age: an optional age for the animal @@ -1955,12 +1963,12 @@ The reStructuredText domain (name **rst**) provides the following directives: will be rendered as: .. rst:directive:: foo - :noindex: + :nocontentsentry: Foo description. .. rst:directive:: .. bar:: baz - :noindex: + :nocontentsentry: Bar description. @@ -1979,13 +1987,13 @@ The reStructuredText domain (name **rst**) provides the following directives: will be rendered as: .. rst:directive:: toctree - :noindex: + :nocontentsentry: .. rst:directive:option:: caption: caption of ToC - :noindex: + :nocontentsentry: .. rst:directive:option:: glob - :noindex: + :nocontentsentry: .. rubric:: options @@ -2014,7 +2022,7 @@ The reStructuredText domain (name **rst**) provides the following directives: will be rendered as: .. rst:role:: foo - :noindex: + :nocontentsentry: Foo description. 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)