mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Implement :no-index-entry:
for autodoc (#12233)
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This commit is contained in:
@@ -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
|
||||
----------
|
||||
|
@@ -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
|
||||
|
||||
|
@@ -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,
|
||||
|
@@ -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',
|
||||
|
@@ -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)
|
||||
|
Reference in New Issue
Block a user