Implement :no-index-entry: for autodoc (sphinx-doc#12233)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

Author: sneakers-the-rat

CHANGES.rst

@@ -76,6 +76,10 @@ Features added
 * #13272: The Python and JavaScript module directives now support
   the ``:no-index-entry:`` option.
   Patch by Adam Turner.
+* #12233: autodoc: Allow directives to use ``:no-index-entry:``
+  and include the ``:no-index:`` and ``:no-index-entry:`` options within
+  :confval:`autodoc_default_options`.
+  Patch by Jonny Saunders and Adam Turner.
 
 Bugs fixed
 ----------

doc/usage/extensions/autodoc.rst

@@ -326,6 +326,15 @@ Automatically document modules
 
       .. versionadded:: 0.4
 
+   .. rst:directive:option:: no-index-entry
+      :type:
+
+      Do not generate an index entry for the documented module
+      or any auto-documented members.
+      Unlike ``:no-index:``, cross-references are still created.
+
+      .. versionadded:: 8.2
+
    .. rst:directive:option:: platform: platforms
       :type: comma separated list
 
@@ -578,6 +587,15 @@ Automatically document classes or exceptions
 
       .. versionadded:: 0.4
 
+   .. rst:directive:option:: no-index-entry
+      :type:
+
+      Do not generate an index entry for the documented class
+      or any auto-documented members.
+      Unlike ``:no-index:``, cross-references are still created.
+
+      .. versionadded:: 8.2
+
    .. rst:directive:option:: class-doc-from
       :type: class, init, or both
 
@@ -854,6 +872,14 @@ Automatically document function-like objects
 
       .. versionadded:: 0.4
 
+   .. rst:directive:option:: no-index-entry
+      :type:
+
+      Do not generate an index entry for the documented function.
+      Unlike ``:no-index:``, cross-references are still created.
+
+      .. versionadded:: 8.2
+
 
 Automatically document attributes or data
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -900,11 +926,18 @@ Automatically document attributes or data
    .. rst:directive:option:: no-index
       :type:
 
-      Do not generate an index entry for the documented class
-      or any auto-documented members.
+      Do not generate an index entry for the documented variable or constant.
 
       .. versionadded:: 0.4
 
+   .. rst:directive:option:: no-index-entry
+      :type:
+
+      Do not generate an index entry for the documented variable or constant.
+      Unlike ``:no-index:``, cross-references are still created.
+
+      .. versionadded:: 8.2
+
    .. rst:directive:option:: annotation: value
       :type: string
 
@@ -1039,6 +1072,8 @@ There are also config values that you can set:
    * ``'show-inheritance'``: See :rst:dir:`autoclass:show-inheritance`.
    * ``'class-doc-from'``: See :rst:dir:`autoclass:class-doc-from`.
    * ``'no-value'``: See :rst:dir:`autodata:no-value`.
+   * ``'no-index'``: See :rst:dir:`automodule:no-index`.
+   * ``'no-index-entry'``: See :rst:dir:`automodule:no-index-entry`.
 
    .. versionadded:: 1.8
 

sphinx/ext/autodoc/__init__.py

@@ -365,6 +365,7 @@ class Documenter:
 
     option_spec: ClassVar[OptionSpec] = {
         'no-index': bool_option,
+        'no-index-entry': bool_option,
         'noindex': bool_option,
     }
 
@@ -605,6 +606,8 @@ def add_directive_header(self, sig: str) -> None:
 
         if self.options.no_index or self.options.noindex:
             self.add_line('   :no-index:', sourcename)
+        if self.options.no_index_entry:
+            self.add_line('   :no-index-entry:', sourcename)
         if self.objpath:
             # Be explicit about the module, this is necessary since .. class::
             # etc. don't support a prepended module name
@@ -1110,6 +1113,7 @@ class ModuleDocumenter(Documenter):
         'members': members_option,
         'undoc-members': bool_option,
         'no-index': bool_option,
+        'no-index-entry': bool_option,
         'inherited-members': inherited_members_option,
         'show-inheritance': bool_option,
         'synopsis': identity,
@@ -1197,6 +1201,8 @@ def add_directive_header(self, sig: str) -> None:
             self.add_line('   :platform: ' + self.options.platform, sourcename)
         if self.options.deprecated:
             self.add_line('   :deprecated:', sourcename)
+        if self.options.no_index_entry:
+            self.add_line('   :no-index-entry:', sourcename)
 
     def get_module_members(self) -> dict[str, ObjectMember]:
         """Get members of target module."""
@@ -1625,6 +1631,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         'members': members_option,
         'undoc-members': bool_option,
         'no-index': bool_option,
+        'no-index-entry': bool_option,
         'inherited-members': inherited_members_option,
         'show-inheritance': bool_option,
         'member-order': member_order_option,

sphinx/ext/autodoc/directive.py

@@ -30,6 +30,8 @@
 AUTODOC_DEFAULT_OPTIONS = [
     'members',
     'undoc-members',
+    'no-index',
+    'no-index-entry',
     'inherited-members',
     'show-inheritance',
     'private-members',

tests/test_extensions/test_ext_autodoc.py

@@ -3180,3 +3180,32 @@ def function_rst(name, sig):
         *function_rst('bar', 'x: typing.Literal[1234]'),
         *function_rst('foo', 'x: typing.Literal[target.literal.MyEnum.a]'),
     ]
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_no_index_entry(app):
+    # modules can use no-index-entry
+    options = {'no-index-entry': None}
+    actual = do_autodoc(app, 'module', 'target.module', options)
+    assert '   :no-index-entry:' in list(actual)
+
+    # classes can use no-index-entry
+    actual = do_autodoc(app, 'class', 'target.classes.Foo', options)
+    assert '   :no-index-entry:' in list(actual)
+
+    # functions can use no-index-entry
+    actual = do_autodoc(app, 'function', 'target.functions.func', options)
+    assert '   :no-index-entry:' in list(actual)
+
+    # modules respect no-index-entry in autodoc_default_options
+    app.config.autodoc_default_options = {'no-index-entry': True}
+    actual = do_autodoc(app, 'module', 'target.module')
+    assert '   :no-index-entry:' in list(actual)
+
+    # classes respect config-level no-index-entry
+    actual = do_autodoc(app, 'class', 'target.classes.Foo')
+    assert '   :no-index-entry:' in list(actual)
+
+    # functions respect config-level no-index-entry
+    actual = do_autodoc(app, 'function', 'target.functions.func')
+    assert '   :no-index-entry:' in list(actual)