Merge branch 'master' into autosummary-short-signature

Author: timhoffm

CHANGES.rst

@@ -31,7 +31,7 @@ Deprecated
 Features added
 --------------
 
-* Add a new ``duplicate_declaration`` warning type,
+* #13173: Add a new ``duplicate_declaration`` warning type,
   with ``duplicate_declaration.c`` and ``duplicate_declaration.cpp`` subtypes.
   Patch by Julien Lecomte and Adam Turner.
 * #11824: linkcode: Allow extensions to add support for a domain by defining
@@ -46,9 +46,9 @@ Features added
   Patch by Adam Turner.
 * #13065: Enable colour by default in when running on CI.
   Patch by Adam Turner.
-* Allow supressing warnings from the :rst:dir:`toctree` directive when a glob
-  pattern doesn't match any documents, via the new ``toc.empty_glob``
-  warning sub-type.
+* #13230: Allow supressing warnings from the :rst:dir:`toctree` directive
+  when a glob pattern doesn't match any documents,
+  via the new ``toc.empty_glob`` warning sub-type.
   Patch by Slawek Figiel.
 * #9732: Add the new ``autodoc.mocked_object`` warnings sub-type.
   Patch by Cyril Roelandt.
@@ -73,6 +73,13 @@ Features added
 * #9732: Add the new ``ref.any`` warnings sub-type
   to allow suppressing the ambiguous 'any' cross-reference warning.
   Patch by Simão Afonso and Adam Turner.
+* #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.
 * #13172: Add support for short signatures in autosummary.
   Patch by Tim Hoffmann
 
@@ -86,8 +93,7 @@ Bugs fixed
 * #13130: LaTeX docs: ``pdflatex`` index creation may fail for index entries
   in French.  See :confval:`latex_use_xindy`.
   Patch by Jean-François B.
-* LaTeX: fix a ``7.4.0`` typo in a default for ``\sphinxboxsetup``
-  (refs: PR #13152).
+* #13152: LaTeX: fix a typo from v7.4.0 in a default for ``\sphinxboxsetup``.
   Patch by Jean-François B.
 * #13096: HTML Search: check that query terms exist as properties in
   term indices before accessing them.

doc/usage/domains/index.rst

@@ -48,7 +48,7 @@ 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.
+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 ``:no-index-entry:``.
 If you want to exclude the object description from the table of contents, you

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
 

doc/usage/referencing.rst

@@ -254,6 +254,9 @@ The following role creates a cross-reference to a term in a
    If you use a term that's not explained in a glossary, you'll get a warning
    during build.
 
+   This role also supports :ref:`custom link text <xref-modifiers>` from the general
+   cross-reference syntax.
+
 
 .. _any-role:
 

sphinx/domains/javascript.py

@@ -155,8 +155,8 @@ def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
     def add_target_and_index(
         self, name_obj: tuple[str, str], sig: str, signode: desc_signature
     ) -> None:
-        mod_name = self.env.ref_context.get('js:module')
-        fullname = (mod_name + '.' if mod_name else '') + name_obj[0]
+        mod_name = self.env.ref_context.get('js:module', '')
+        fullname = (f'{mod_name}.' if mod_name else '') + name_obj[0]
         node_id = make_id(self.env, self.state.document, '', fullname)
         signode['ids'].append(node_id)
         self.state.document.note_explicit_target(signode)
@@ -165,11 +165,10 @@ def add_target_and_index(
         domain.note_object(fullname, self.objtype, node_id, location=signode)
 
         if 'no-index-entry' not in self.options:
-            indextext = self.get_index_text(mod_name, name_obj)  # type: ignore[arg-type]
-            if indextext:
+            if index_text := self.get_index_text(mod_name, name_obj):
                 self.indexnode['entries'].append((
                     'single',
-                    indextext,
+                    index_text,
                     node_id,
                     '',
                     None,
@@ -333,6 +332,7 @@ class JSModule(SphinxDirective):
     final_argument_whitespace = False
     option_spec: ClassVar[OptionSpec] = {
         'no-index': directives.flag,
+        'no-index-entry': directives.flag,
         'no-contents-entry': directives.flag,
         'no-typesetting': directives.flag,
         'noindex': directives.flag,
@@ -365,9 +365,12 @@ def run(self) -> list[Node]:
             )
 
             # The node order is: index node first, then target node
-            indextext = _('%s (module)') % mod_name
-            inode = addnodes.index(entries=[('single', indextext, node_id, '', None)])
-            ret.append(inode)
+            if 'no-index-entry' not in self.options:
+                index_text = _('%s (module)') % mod_name
+                inode = addnodes.index(
+                    entries=[('single', index_text, node_id, '', None)]
+                )
+                ret.append(inode)
             target = nodes.target('', '', ids=[node_id], ismod=True)
             self.state.document.note_explicit_target(target)
             ret.append(target)

sphinx/domains/python/__init__.py

@@ -479,6 +479,7 @@ class PyModule(SphinxDirective):
         'platform': lambda x: x,
         'synopsis': lambda x: x,
         'no-index': directives.flag,
+        'no-index-entry': directives.flag,
         'no-contents-entry': directives.flag,
         'no-typesetting': directives.flag,
         'noindex': directives.flag,
@@ -520,10 +521,15 @@ def run(self) -> list[Node]:
 
             # the platform and synopsis aren't printed; in fact, they are only
             # used in the modindex currently
-            indextext = f'module; {modname}'
-            inode = addnodes.index(entries=[('pair', indextext, node_id, '', None)])
-            # The node order is: index node first, then target node.
-            ret.extend((inode, target))
+
+            if 'no-index-entry' not in self.options:
+                index_text = f'module; {modname}'
+                inode = addnodes.index(
+                    entries=[('pair', index_text, node_id, '', None)]
+                )
+                # The node order is: index node first, then target node.
+                ret.append(inode)
+            ret.append(target)
         ret.extend(content_nodes)
         return ret
 

sphinx/domains/python/_object.py

@@ -409,8 +409,8 @@ def get_index_text(self, modname: str, name: tuple[str, str]) -> str:
     def add_target_and_index(
         self, name_cls: tuple[str, str], sig: str, signode: desc_signature
     ) -> None:
-        modname = self.options.get('module', self.env.ref_context.get('py:module'))
-        fullname = (f'{modname}.' if modname else '') + name_cls[0]
+        mod_name = self.options.get('module', self.env.ref_context.get('py:module'))
+        fullname = (f'{mod_name}.' if mod_name else '') + name_cls[0]
         node_id = make_id(self.env, self.state.document, '', fullname)
         signode['ids'].append(node_id)
         self.state.document.note_explicit_target(signode)
@@ -425,11 +425,10 @@ def add_target_and_index(
             )
 
         if 'no-index-entry' not in self.options:
-            indextext = self.get_index_text(modname, name_cls)
-            if indextext:
+            if index_text := self.get_index_text(mod_name, name_cls):
                 self.indexnode['entries'].append((
                     'single',
-                    indextext,
+                    index_text,
                     node_id,
                     '',
                     None,

sphinx/domains/rst.py

@@ -57,11 +57,10 @@ def add_target_and_index(
         domain.note_object(self.objtype, name, node_id, location=signode)
 
         if 'no-index-entry' not in self.options:
-            indextext = self.get_index_text(self.objtype, name)
-            if indextext:
+            if index_text := self.get_index_text(self.objtype, name):
                 self.indexnode['entries'].append((
                     'single',
-                    indextext,
+                    index_text,
                     node_id,
                     '',
                     None,

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',