Consistently name the object description options (#11533)

*  The directive option ``:noindex:`` was renamed to ``:no-index:``.
*  The directive option ``:noindexentry:`` was renamed to ``:no-index-entry:``.
*  The directive option ``:nocontentsentry:`` was renamed to ``:no-contents-entry:``.

The previous names are retained as aliases, but will be deprecated
and removed in a future version of Sphinx (9.0 or later).

doc/development/overview.rst

@@ -12,7 +12,7 @@ project's :file:`conf.py` file, but this is not available to you as an
 extension developer.
 
 .. module:: sphinx.application
-    :noindex:
+   :no-index:
 
 To ensure that another extension is activated as a part of your own extension,
 use the :meth:`sphinx.application.Sphinx.setup_extension` method. This will

doc/development/templating.rst

@@ -226,7 +226,7 @@ them to generate links or output multiply used elements.
    documents.
 
 .. function:: pathto(file, 1)
-   :noindex:
+   :no-index:
 
    Return the path to a *file* which is a filename relative to the root of the
    generated output.  Use this to refer to static files.

doc/extdev/appapi.rst

@@ -105,7 +105,7 @@ Emitting events
 ---------------
 
 .. class:: Sphinx
-   :noindex:
+   :no-index:
 
    .. automethod:: emit
 

doc/usage/extensions/autodoc.rst

@@ -303,7 +303,7 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
      .. versionadded:: 0.4
 
-   * All autodoc directives support the ``noindex`` flag option that has the
+   * All autodoc directives support the ``no-index`` flag option that has the
      same effect as for standard :rst:dir:`py:function` etc. directives: no
      index entries are generated for the documented object (and all
      autodocumented members).
@@ -724,7 +724,7 @@ There are also config values that you can set:
    .. versionadded:: 1.7
 
 .. confval:: suppress_warnings
-   :noindex:
+   :no-index:
 
    :mod:`autodoc` supports to suppress warning messages via
    :confval:`suppress_warnings`.  It allows following warnings types in
@@ -755,7 +755,7 @@ autodoc provides the following additional events:
    :param obj: the object itself
    :param options: the options given to the directive: an object with attributes
       ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
-      ``noindex`` that are true if the flag option of same name was given to the
+      ``no-index`` that are true if the flag option of same name was given to the
       auto directive
    :param lines: the lines of the docstring, see above
 
@@ -786,7 +786,7 @@ autodoc provides the following additional events:
    :param obj: the object itself
    :param options: the options given to the directive: an object with attributes
       ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
-      ``noindex`` that are true if the flag option of same name was given to the
+      ``no-index`` that are true if the flag option of same name was given to the
       auto directive
    :param signature: function signature, as a string of the form
       ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't
@@ -849,5 +849,5 @@ member should be included in the documentation by using the following event:
       user handler does not override the decision
    :param options: the options given to the directive: an object with attributes
       ``inherited_members``, ``undoc_members``, ``show_inheritance`` and
-      ``noindex`` that are true if the flag option of same name was given to the
+      ``no-index`` that are true if the flag option of same name was given to the
       auto directive

doc/usage/extensions/autosummary.rst

@@ -349,7 +349,7 @@ Additionally, the following filters are available
    replaces the builtin Jinja `escape filter`_ that does html-escaping.
 
 .. function:: underline(s, line='=')
-   :noindex:
+   :no-index:
 
    Add a title underline to a piece of text.
 

doc/usage/extensions/inheritance.rst

@@ -132,8 +132,8 @@ part (``sphinx``) from all names::
    :parts: -1
 
 .. py:class:: sphinx.ext.inheritance_diagram.InheritanceDiagram
-   :nocontentsentry:
-   :noindexentry:
+   :no-contents-entry:
+   :no-index-entry:
 
    The internal class that implements the ``inheritance-diagram`` directive.
 

doc/usage/restructuredtext/domains.rst

@@ -48,12 +48,12 @@ 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:``.
+give the directive option flag ``:no-index-entry:``.
 If you want to exclude the object description from the table of contents, you
-can give the directive option flag ``:nocontentsentry:``.
+can give the directive option flag ``:no-contents-entry:``.
 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:``).
+for cross-referencing, you can give the directive option flag ``:no-index:``
+(which implies ``:no-index-entry:``).
 If you do not want to typeset anything, you can give the directive option flag
 ``:no-typesetting:``.  This can for example be used to create only a target and
 index entry for later reference.
@@ -72,6 +72,19 @@ options.
    The directive option ``no-typesetting`` in the Python, C, C++, Javascript,
    and reStructuredText domains.
 
+.. versionchanged:: 7.2
+
+   *  The directive option ``:noindex:`` was renamed
+      to ``:no-index:``.
+   *  The directive option ``:noindexentry:`` was renamed
+      to ``:no-index-entry:``.
+   *  The directive option ``:nocontentsentry:`` was renamed
+      to ``:no-contents-entry:``.
+
+   The previous names are retained as aliases,
+   but will be deprecated and removed
+   in a future version of Sphinx.
+
 An example using a Python domain directive::
 
    .. py:function:: spam(eggs)
@@ -85,9 +98,9 @@ that are continued in the next line.  Example::
 
    .. py:function:: filterwarnings(action, message='', category=Warning, \
                                    module='', lineno=0, append=False)
-      :noindex:
+      :no-index:
 
-(This example also shows how to use the ``:noindex:`` flag.)
+(This example also shows how to use the ``:no-index:`` flag.)
 
 The domains also provide roles that link back to these object descriptions.
 For example, to link to one of the functions described in the example above,
@@ -643,7 +656,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:
+   :no-index:
 
 It is customary to put the opening bracket before the comma.
 
@@ -721,7 +734,7 @@ explained by an example::
 This will render like this:
 
 .. py:function:: send_message(sender, recipient, message_body, [priority=1])
-   :noindex:
+   :no-index:
 
    Send a message to a recipient
 
@@ -1021,20 +1034,20 @@ Example::
 This will be rendered as:
 
 .. c:struct:: Data
-   :nocontentsentry:
-   :noindexentry:
+   :no-contents-entry:
+   :no-index-entry:
 
    .. c:union:: @data
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
       .. c:var:: int a
-         :nocontentsentry:
-         :noindexentry:
+         :no-contents-entry:
+         :no-index-entry:
 
       .. c:var:: double b
-         :nocontentsentry:
-         :noindexentry:
+         :no-contents-entry:
+         :no-index-entry:
 
 Explicit ref: :c:var:`Data.@data.a`. Short-hand ref: :c:var:`Data.a`.
 
@@ -1116,12 +1129,12 @@ Inline Expressions and Types
    will be rendered as follows:
 
    .. c:var:: int a = 42
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
    .. c:function:: int f(int i)
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
    An expression: :c:expr:`a * f(a)` (or as text: :c:texpr:`a * f(a)`).
 
@@ -1340,27 +1353,27 @@ visibility statement (``public``, ``private`` or ``protected``).
    The example are rendered as follows.
 
    .. cpp:type:: std::vector<int> MyList
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
       A typedef-like declaration of a type.
 
    .. cpp:type:: MyContainer::const_iterator
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
       Declaration of a type alias with unspecified type.
 
    .. cpp:type:: MyType = std::unordered_map<int, std::string>
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
       Declaration of a type alias.
 
    .. cpp:type:: template<typename T> \
                  MyContainer = std::vector<T>
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
 .. rst:directive:: .. cpp:enum:: unscoped enum declaration
                    .. cpp:enum-struct:: scoped enum declaration
@@ -1455,7 +1468,7 @@ Options
 
 Some directives support options:
 
-- ``:noindexentry:`` and ``:nocontentsentry:``, see :ref:`basic-domain-markup`.
+- ``:no-index-entry:`` and ``:no-contents-entry:``, see :ref:`basic-domain-markup`.
 - ``:tparam-line-spec:``, for templated declarations.
   If specified, each template parameter will be rendered on a separate line.
 
@@ -1487,20 +1500,20 @@ Example::
 This will be rendered as:
 
 .. cpp:class:: Data
-   :nocontentsentry:
-   :noindexentry:
+   :no-contents-entry:
+   :no-index-entry:
 
    .. cpp:union:: @data
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
       .. cpp:var:: int a
-         :nocontentsentry:
-         :noindexentry:
+         :no-contents-entry:
+         :no-index-entry:
 
       .. cpp:var:: double b
-         :nocontentsentry:
-         :noindexentry:
+         :no-contents-entry:
+         :no-index-entry:
 
 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
 
@@ -1606,14 +1619,14 @@ introduction` instead of a template parameter list::
 They are rendered as follows.
 
 .. cpp:function:: std::Iterator{It} void advance(It &it)
-   :nocontentsentry:
-   :noindexentry:
+   :no-contents-entry:
+   :no-index-entry:
 
    A function template with a template parameter constrained to be an Iterator.
 
 .. cpp:class:: std::LessThanComparable{T} MySortedContainer
-   :nocontentsentry:
-   :noindexentry:
+   :no-contents-entry:
+   :no-index-entry:
 
    A class template with a template parameter constrained to be
    LessThanComparable.
@@ -1643,12 +1656,12 @@ Inline Expressions and Types
    will be rendered as follows:
 
    .. cpp:var:: int a = 42
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
    .. cpp:function:: int f(int i)
-      :nocontentsentry:
-      :noindexentry:
+      :no-contents-entry:
+      :no-index-entry:
 
    An expression: :cpp:expr:`a * f(a)` (or as text: :cpp:texpr:`a * f(a)`).
 
@@ -2037,7 +2050,7 @@ The JavaScript domain (name **js**) provides the following directives:
    :rst:dir:`py:class` would, for example.
 
    By default, this directive will create a linkable entity and will cause an
-   entry in the global module index, unless the ``noindex`` option is
+   entry in the global module index, unless the ``no-index`` option is
    specified.  If this option is specified, the directive will only update the
    current module name.
 
@@ -2069,7 +2082,7 @@ The JavaScript domain (name **js**) provides the following directives:
    This is rendered as:
 
    .. js:function:: $.getJSON(href, callback[, errback])
-      :noindex:
+      :no-index:
 
       :param string href: An URI to the location of the resource.
       :param callback: Gets called with the object.
@@ -2117,7 +2130,7 @@ The JavaScript domain (name **js**) provides the following directives:
    This is rendered as:
 
    .. js:class:: MyAnimal(name[, age])
-      :noindex:
+      :no-index:
 
       :param string name: The name of the animal
       :param number age: an optional age for the animal
@@ -2173,12 +2186,12 @@ The reStructuredText domain (name **rst**) provides the following directives:
    will be rendered as:
 
    .. rst:directive:: foo
-      :noindex:
+      :no-index:
 
       Foo description.
 
    .. rst:directive:: .. bar:: baz
-      :noindex:
+      :no-index:
 
       Bar description.
 
@@ -2197,13 +2210,13 @@ The reStructuredText domain (name **rst**) provides the following directives:
    will be rendered as:
 
    .. rst:directive:: toctree
-      :noindex:
+      :no-index:
 
       .. rst:directive:option:: caption: caption of ToC
-         :noindex:
+         :no-index:
 
       .. rst:directive:option:: glob
-         :noindex:
+         :no-index:
 
    .. rubric:: options
 
@@ -2232,7 +2245,7 @@ The reStructuredText domain (name **rst**) provides the following directives:
    will be rendered as:
 
    .. rst:role:: foo
-      :noindex:
+      :no-index:
 
       Foo description.