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

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This commit is contained in:
Jonny Saunders
2025-01-27 18:01:31 -08:00
committed by GitHub
parent 7801540c08
commit 18bb8bcef5
5 changed files with 79 additions and 2 deletions

View File

@@ -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
----------

View File

@@ -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

View File

@@ -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 @@ class Documenter:
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 @@ class ModuleDocumenter(Documenter):
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,

View File

@@ -30,6 +30,8 @@ logger = logging.getLogger(__name__)
AUTODOC_DEFAULT_OPTIONS = [
'members',
'undoc-members',
'no-index',
'no-index-entry',
'inherited-members',
'show-inheritance',
'private-members',

View File

@@ -3180,3 +3180,32 @@ def test_literal_render(app):
*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)