IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Define valid types for all configuration values (#13324)

Browse Source
This commit is contained in:
Adam Turner
2025-02-10 01:58:22 +00:00
committed by GitHub
parent b59d1b7513
commit f96904146f
33 changed files with 418 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
sphinx/builders/epub3.py
View File

@@ -287,33 +287,65 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(Epub3Builder)
# config values
app.add_config_value('epub_basename', lambda self: make_filename(self.project), '')
app.add_config_value('epub_version', 3.0, 'epub') # experimental
app.add_config_value('epub_theme', 'epub', 'epub')
app.add_config_value('epub_theme_options', {}, 'epub')
app.add_config_value('epub_title', lambda self: self.project, 'epub')
app.add_config_value('epub_author', lambda self: self.author, 'epub')
app.add_config_value('epub_language', lambda self: self.language or 'en', 'epub')
app.add_config_value('epub_publisher', lambda self: self.author, 'epub')
app.add_config_value('epub_copyright', lambda self: self.copyright, 'epub')
app.add_config_value('epub_identifier', 'unknown', 'epub')
app.add_config_value('epub_scheme', 'unknown', 'epub')
app.add_config_value('epub_uid', 'unknown', 'env')
app.add_config_value('epub_cover', (), 'env')
app.add_config_value('epub_guide', (), 'env')
app.add_config_value('epub_pre_files', [], 'env')
app.add_config_value('epub_post_files', [], 'env')
app.add_config_value('epub_css_files', lambda config: config.html_css_files, 'epub')
app.add_config_value('epub_exclude_files', [], 'env')
app.add_config_value('epub_tocdepth', 3, 'env')
app.add_config_value('epub_tocdup', True, 'env')
app.add_config_value('epub_tocscope', 'default', 'env')
app.add_config_value('epub_fix_images', False, 'env')
app.add_config_value('epub_max_image_width', 0, 'env')
app.add_config_value('epub_show_urls', 'inline', 'epub')
app.add_config_value('epub_use_index', lambda self: self.html_use_index, 'epub')
app.add_config_value('epub_description', 'unknown', 'epub')
app.add_config_value('epub_contributor', 'unknown', 'epub')
app.add_config_value(
'epub_basename',
lambda self: make_filename(self.project),
'',
types=frozenset({str}),
)
app.add_config_value(
'epub_version', 3.0, 'epub', types=frozenset({float})
) # experimental
app.add_config_value('epub_theme', 'epub', 'epub', types=frozenset({str}))
app.add_config_value('epub_theme_options', {}, 'epub', types=frozenset({dict}))
app.add_config_value(
'epub_title', lambda self: self.project, 'epub', types=frozenset({str})
)
app.add_config_value(
'epub_author', lambda self: self.author, 'epub', types=frozenset({str})
)
app.add_config_value(
'epub_language',
lambda self: self.language or 'en',
'epub',
types=frozenset({str}),
)
app.add_config_value(
'epub_publisher', lambda self: self.author, 'epub', types=frozenset({str})
)
app.add_config_value(
'epub_copyright', lambda self: self.copyright, 'epub', types=frozenset({str})
)
app.add_config_value('epub_identifier', 'unknown', 'epub', types=frozenset({str}))
app.add_config_value('epub_scheme', 'unknown', 'epub', types=frozenset({str}))
app.add_config_value('epub_uid', 'unknown', 'env', types=frozenset({str}))
app.add_config_value('epub_cover', (), 'env', types=frozenset({list, tuple}))
app.add_config_value('epub_guide', (), 'env', types=frozenset({list, tuple}))
app.add_config_value('epub_pre_files', [], 'env', types=frozenset({list, tuple}))
app.add_config_value('epub_post_files', [], 'env', types=frozenset({list, tuple}))
app.add_config_value(
'epub_css_files',
lambda config: config.html_css_files,
'epub',
types=frozenset({list, tuple}),
)
app.add_config_value(
'epub_exclude_files', [], 'env', types=frozenset({list, tuple})
)
app.add_config_value('epub_tocdepth', 3, 'env', types=frozenset({int}))
app.add_config_value('epub_tocdup', True, 'env', types=frozenset({bool}))
app.add_config_value('epub_tocscope', 'default', 'env', types=frozenset({str}))
app.add_config_value('epub_fix_images', False, 'env', types=frozenset({bool}))
app.add_config_value('epub_max_image_width', 0, 'env', types=frozenset({int}))
app.add_config_value('epub_show_urls', 'inline', 'epub', types=frozenset({str}))
app.add_config_value(
'epub_use_index',
lambda self: self.html_use_index,
'epub',
types=frozenset({bool}),
)
app.add_config_value('epub_description', 'unknown', 'epub', types=frozenset({str}))
app.add_config_value('epub_contributor', 'unknown', 'epub', types=frozenset({str}))
app.add_config_value(
'epub_writing_mode', 'horizontal', 'epub', types=ENUM('horizontal', 'vertical')
)

23
sphinx/builders/gettext.py
View File

@@ -332,16 +332,27 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value(
'gettext_compact', True, 'gettext', types=frozenset({bool, str})
)
app.add_config_value('gettext_location', True, 'gettext')
app.add_config_value('gettext_uuid', False, 'gettext')
app.add_config_value('gettext_auto_build', True, 'env')
app.add_config_value('gettext_location', True, 'gettext', types=frozenset({bool}))
app.add_config_value('gettext_uuid', False, 'gettext', types=frozenset({bool}))
app.add_config_value('gettext_auto_build', True, 'env', types=frozenset({bool}))
app.add_config_value(
'gettext_additional_targets', [], 'env', types=frozenset({set, list})
'gettext_additional_targets',
[],
'env',
types=frozenset({frozenset, list, set, tuple}),
)
app.add_config_value(
'gettext_last_translator', 'FULL NAME <EMAIL@ADDRESS>', 'gettext'
'gettext_last_translator',
'FULL NAME <EMAIL@ADDRESS>',
'gettext',
types=frozenset({str}),
)
app.add_config_value(
'gettext_language_team',
'LANGUAGE <LL@li.org>',
'gettext',
types=frozenset({str}),
)
app.add_config_value('gettext_language_team', 'LANGUAGE <LL@li.org>', 'gettext')
return {
'version': 'builtin',

84
sphinx/builders/html/__init__.py
View File

@@ -12,6 +12,7 @@ import shutil
import sys
import warnings
from pathlib import Path
from types import NoneType
from typing import TYPE_CHECKING
from urllib.parse import quote
@@ -1439,60 +1440,77 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(StandaloneHTMLBuilder)
# config values
app.add_config_value('html_theme', 'alabaster', 'html')
app.add_config_value('html_theme_path', [], 'html')
app.add_config_value('html_theme_options', {}, 'html')
app.add_config_value('html_theme', 'alabaster', 'html', types=frozenset({str}))
app.add_config_value('html_theme_path', [], 'html', types=frozenset({list, tuple}))
app.add_config_value('html_theme_options', {}, 'html', types=frozenset({dict}))
app.add_config_value(
'html_title',
lambda c: _('%s %s documentation') % (c.project, c.release),
'html',
types=frozenset({str}),
)
app.add_config_value('html_short_title', lambda self: self.html_title, 'html')
app.add_config_value('html_style', None, 'html', types=frozenset({list, str}))
app.add_config_value(
'html_short_title', lambda self: self.html_title, 'html', types=frozenset({str})
)
app.add_config_value(
'html_style', None, 'html', types=frozenset({list, str, tuple})
)
app.add_config_value('html_logo', None, 'html', types=frozenset({str}))
app.add_config_value('html_favicon', None, 'html', types=frozenset({str}))
app.add_config_value('html_css_files', [], 'html')
app.add_config_value('html_js_files', [], 'html')
app.add_config_value('html_static_path', [], 'html')
app.add_config_value('html_extra_path', [], 'html')
app.add_config_value('html_css_files', [], 'html', types=frozenset({list, tuple}))
app.add_config_value('html_js_files', [], 'html', types=frozenset({list, tuple}))
app.add_config_value('html_static_path', [], 'html', types=frozenset({list, tuple}))
app.add_config_value('html_extra_path', [], 'html', types=frozenset({list, tuple}))
app.add_config_value('html_last_updated_fmt', None, 'html', types=frozenset({str}))
app.add_config_value(
'html_last_updated_use_utc', False, 'html', types=frozenset({bool})
)
app.add_config_value('html_sidebars', {}, 'html')
app.add_config_value('html_additional_pages', {}, 'html')
app.add_config_value('html_sidebars', {}, 'html', types=frozenset({dict}))
app.add_config_value('html_additional_pages', {}, 'html', types=frozenset({dict}))
app.add_config_value(
'html_domain_indices', True, 'html', types=frozenset({set, list})
'html_domain_indices',
True,
'html',
types=frozenset({frozenset, list, set, tuple}),
)
app.add_config_value('html_permalinks', True, 'html')
app.add_config_value('html_permalinks_icon', '', 'html')
app.add_config_value('html_use_index', True, 'html')
app.add_config_value('html_split_index', False, 'html')
app.add_config_value('html_copy_source', True, 'html')
app.add_config_value('html_show_sourcelink', True, 'html')
app.add_config_value('html_sourcelink_suffix', '.txt', 'html')
app.add_config_value('html_use_opensearch', '', 'html')
app.add_config_value('html_permalinks', True, 'html', types=frozenset({bool}))
app.add_config_value('html_permalinks_icon', '', 'html', types=frozenset({str}))
app.add_config_value('html_use_index', True, 'html', types=frozenset({bool}))
app.add_config_value('html_split_index', False, 'html', types=frozenset({bool}))
app.add_config_value('html_copy_source', True, 'html', types=frozenset({bool}))
app.add_config_value('html_show_sourcelink', True, 'html', types=frozenset({bool}))
app.add_config_value(
'html_sourcelink_suffix', '.txt', 'html', types=frozenset({str})
)
app.add_config_value('html_use_opensearch', '', 'html', types=frozenset({str}))
app.add_config_value('html_file_suffix', None, 'html', types=frozenset({str}))
app.add_config_value('html_link_suffix', None, 'html', types=frozenset({str}))
app.add_config_value('html_show_copyright', True, 'html')
app.add_config_value('html_show_search_summary', True, 'html')
app.add_config_value('html_show_sphinx', True, 'html')
app.add_config_value('html_context', {}, 'html')
app.add_config_value('html_output_encoding', 'utf-8', 'html')
app.add_config_value('html_compact_lists', True, 'html')
app.add_config_value('html_secnumber_suffix', '. ', 'html')
app.add_config_value('html_show_copyright', True, 'html', types=frozenset({bool}))
app.add_config_value(
'html_show_search_summary', True, 'html', types=frozenset({bool})
)
app.add_config_value('html_show_sphinx', True, 'html', types=frozenset({bool}))
app.add_config_value('html_context', {}, 'html', types=frozenset({dict}))
app.add_config_value(
'html_output_encoding', 'utf-8', 'html', types=frozenset({str})
)
app.add_config_value('html_compact_lists', True, 'html', types=frozenset({bool}))
app.add_config_value('html_secnumber_suffix', '. ', 'html', types=frozenset({str}))
app.add_config_value('html_search_language', None, 'html', types=frozenset({str}))
app.add_config_value('html_search_options', {}, 'html')
app.add_config_value('html_search_scorer', '', '')
app.add_config_value('html_scaled_image_link', True, 'html')
app.add_config_value('html_baseurl', '', 'html')
app.add_config_value('html_search_options', {}, 'html', types=frozenset({dict}))
app.add_config_value('html_search_scorer', '', '', types=frozenset({str}))
app.add_config_value(
'html_scaled_image_link', True, 'html', types=frozenset({bool})
)
app.add_config_value('html_baseurl', '', 'html', types=frozenset({str}))
# removal is indefinitely on hold (ref: https://github.com/sphinx-doc/sphinx/issues/10265)
app.add_config_value(
'html_codeblock_linenos_style', 'inline', 'html', types=ENUM('table', 'inline')
)
app.add_config_value('html_math_renderer', None, 'env')
app.add_config_value('html4_writer', False, 'html')
app.add_config_value(
'html_math_renderer', None, 'env', types=frozenset({str, NoneType})
)
app.add_config_value('html4_writer', False, 'html', types=frozenset({bool}))
# events
app.add_event('html-collect-pages')

30
sphinx/builders/latex/__init__.py
View File

@@ -608,10 +608,14 @@ def setup(app: Sphinx) -> ExtensionMetadata:
'',
types=ENUM('pdflatex', 'xelatex', 'lualatex', 'platex', 'uplatex'),
)
app.add_config_value('latex_documents', default_latex_documents, '')
app.add_config_value(
'latex_documents', default_latex_documents, '', types=frozenset({list, tuple})
)
app.add_config_value('latex_logo', None, '', types=frozenset({str}))
app.add_config_value('latex_appendices', [], '')
app.add_config_value('latex_use_latex_multicolumn', False, '')
app.add_config_value('latex_appendices', [], '', types=frozenset({list, tuple}))
app.add_config_value(
'latex_use_latex_multicolumn', False, '', types=frozenset({bool})
)
app.add_config_value(
'latex_use_xindy', default_latex_use_xindy, '', types=frozenset({bool})
)
@@ -621,19 +625,25 @@ def setup(app: Sphinx) -> ExtensionMetadata:
'',
types=ENUM(None, 'part', 'chapter', 'section'),
)
app.add_config_value('latex_domain_indices', True, '', types=frozenset({set, list}))
app.add_config_value('latex_show_urls', 'no', '')
app.add_config_value('latex_show_pagerefs', False, '')
app.add_config_value('latex_elements', {}, '')
app.add_config_value('latex_additional_files', [], '')
app.add_config_value(
'latex_domain_indices', True, '', types=frozenset({frozenset, list, set, tuple})
)
app.add_config_value('latex_show_urls', 'no', '', types=frozenset({str}))
app.add_config_value('latex_show_pagerefs', False, '', types=frozenset({bool}))
app.add_config_value('latex_elements', {}, '', types=frozenset({dict}))
app.add_config_value(
'latex_additional_files', [], '', types=frozenset({list, tuple})
)
app.add_config_value(
'latex_table_style', ['booktabs', 'colorrows'], '', types=frozenset({list})
)
app.add_config_value('latex_theme', 'manual', '', types=frozenset({str}))
app.add_config_value('latex_theme_options', {}, '')
app.add_config_value('latex_theme_options', {}, '', types=frozenset({dict}))
app.add_config_value('latex_theme_path', [], '', types=frozenset({list}))
app.add_config_value('latex_docclass', default_latex_docclass, '')
app.add_config_value(
'latex_docclass', default_latex_docclass, '', types=frozenset({dict})
)
return {
'version': 'builtin',

32
sphinx/builders/linkcheck.py
View File

@@ -768,25 +768,31 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(CheckExternalLinksBuilder)
app.add_post_transform(HyperlinkCollector)
app.add_config_value('linkcheck_ignore', [], '')
app.add_config_value('linkcheck_exclude_documents', [], '')
app.add_config_value('linkcheck_allowed_redirects', {}, '')
app.add_config_value('linkcheck_auth', [], '')
app.add_config_value('linkcheck_request_headers', {}, '')
app.add_config_value('linkcheck_retries', 1, '')
app.add_config_value('linkcheck_timeout', 30, '', types=frozenset({int, float}))
app.add_config_value('linkcheck_workers', 5, '')
app.add_config_value('linkcheck_anchors', True, '')
app.add_config_value('linkcheck_ignore', [], '', types=frozenset({list, tuple}))
app.add_config_value(
'linkcheck_exclude_documents', [], '', types=frozenset({list, tuple})
)
app.add_config_value('linkcheck_allowed_redirects', {}, '', types=frozenset({dict}))
app.add_config_value('linkcheck_auth', [], '', types=frozenset({list, tuple}))
app.add_config_value('linkcheck_request_headers', {}, '', types=frozenset({dict}))
app.add_config_value('linkcheck_retries', 1, '', types=frozenset({int}))
app.add_config_value('linkcheck_timeout', 30, '', types=frozenset({float, int}))
app.add_config_value('linkcheck_workers', 5, '', types=frozenset({int}))
app.add_config_value('linkcheck_anchors', True, '', types=frozenset({bool}))
# Anchors starting with ! are ignored since they are
# commonly used for dynamic pages
app.add_config_value('linkcheck_anchors_ignore', ['^!'], '')
app.add_config_value(
'linkcheck_anchors_ignore_for_url', (), '', types=frozenset({tuple, list})
'linkcheck_anchors_ignore', ['^!'], '', types=frozenset({list, tuple})
)
app.add_config_value(
'linkcheck_rate_limit_timeout', 300.0, '', types=frozenset({int, float})
'linkcheck_anchors_ignore_for_url', (), '', types=frozenset({list, tuple})
)
app.add_config_value(
'linkcheck_rate_limit_timeout', 300.0, '', types=frozenset({float, int})
)
app.add_config_value(
'linkcheck_allow_unauthorized', False, '', types=frozenset({bool})
)
app.add_config_value('linkcheck_allow_unauthorized', False, '')
app.add_config_value(
'linkcheck_report_timeouts_as_broken', False, '', types=frozenset({bool})
)

10
sphinx/builders/manpage.py
View File

@@ -131,9 +131,13 @@ def default_man_pages(config: Config) -> list[tuple[str, str, str, list[str], in
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(ManualPageBuilder)
app.add_config_value('man_pages', default_man_pages, '')
app.add_config_value('man_show_urls', False, '')
app.add_config_value('man_make_section_directory', False, '')
app.add_config_value(
'man_pages', default_man_pages, '', types=frozenset({list, tuple})
)
app.add_config_value('man_show_urls', False, '', types=frozenset({bool}))
app.add_config_value(
'man_make_section_directory', False, '', types=frozenset({bool})
)
return {
'version': 'builtin',

7
sphinx/builders/singlehtml.py
View File

@@ -209,7 +209,12 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.setup_extension('sphinx.builders.html')
app.add_builder(SingleFileHTMLBuilder)
app.add_config_value('singlehtml_sidebars', lambda self: self.html_sidebars, 'html')
app.add_config_value(
'singlehtml_sidebars',
lambda self: self.html_sidebars,
'html',
types=frozenset({dict}),
)
return {
'version': 'builtin',

22
sphinx/builders/texinfo.py
View File

@@ -253,15 +253,23 @@ def default_texinfo_documents(
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(TexinfoBuilder)
app.add_config_value('texinfo_documents', default_texinfo_documents, '')
app.add_config_value('texinfo_appendices', [], '')
app.add_config_value('texinfo_elements', {}, '')
app.add_config_value(
'texinfo_domain_indices', True, '', types=frozenset({set, list})
'texinfo_documents',
default_texinfo_documents,
'',
types=frozenset({list, tuple}),
)
app.add_config_value('texinfo_show_urls', 'footnote', '')
app.add_config_value('texinfo_no_detailmenu', False, '')
app.add_config_value('texinfo_cross_references', True, '')
app.add_config_value('texinfo_appendices', [], '', types=frozenset({list, tuple}))
app.add_config_value('texinfo_elements', {}, '', types=frozenset({dict}))
app.add_config_value(
'texinfo_domain_indices',
True,
'',
types=frozenset({frozenset, list, set, tuple}),
)
app.add_config_value('texinfo_show_urls', 'footnote', '', types=frozenset({str}))
app.add_config_value('texinfo_no_detailmenu', False, '', types=frozenset({bool}))
app.add_config_value('texinfo_cross_references', True, '', types=frozenset({bool}))
return {
'version': 'builtin',

8
sphinx/builders/text.py
View File

@@ -82,10 +82,10 @@ class TextBuilder(Builder):
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(TextBuilder)
app.add_config_value('text_sectionchars', '*=-~"+`', 'env')
app.add_config_value('text_newlines', 'unix', 'env')
app.add_config_value('text_add_secnumbers', True, 'env')
app.add_config_value('text_secnumber_suffix', '. ', 'env')
app.add_config_value('text_sectionchars', '*=-~"+`', 'env', types=frozenset({str}))
app.add_config_value('text_newlines', 'unix', 'env', types=frozenset({str}))
app.add_config_value('text_add_secnumbers', True, 'env', types=frozenset({bool}))
app.add_config_value('text_secnumber_suffix', '. ', 'env', types=frozenset({str}))
return {
'version': 'builtin',

2
sphinx/builders/xml.py
View File

@@ -109,7 +109,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(XMLBuilder)
app.add_builder(PseudoXMLBuilder)
app.add_config_value('xml_pretty', True, 'env')
app.add_config_value('xml_pretty', True, 'env', types=frozenset({bool}))
return {
'version': 'builtin',

91
sphinx/config.py
View File

@@ -94,7 +94,7 @@ class ENUM:
return all(item in self._candidates for item in value)
_OptValidTypes: TypeAlias = tuple[()] | tuple[type, ...] | frozenset[type] | ENUM
_OptValidTypes: TypeAlias = frozenset[type] | ENUM
class _Opt:
@@ -226,86 +226,86 @@ class Config:
config_values: dict[str, _Opt] = {
# general options
'project': _Opt('Project name not set', 'env', ()),
'author': _Opt('Author name not set', 'env', ()),
'project': _Opt('Project name not set', 'env', frozenset((str,))),
'author': _Opt('Author name not set', 'env', frozenset((str,))),
'project_copyright': _Opt('', 'html', frozenset((str, tuple, list))),
'copyright': _Opt(
lambda config: config.project_copyright,
'html',
frozenset((str, tuple, list)),
),
'version': _Opt('', 'env', ()),
'release': _Opt('', 'env', ()),
'today': _Opt('', 'env', ()),
'version': _Opt('', 'env', frozenset((str,))),
'release': _Opt('', 'env', frozenset((str,))),
'today': _Opt('', 'env', frozenset((str,))),
# the real default is locale-dependent
'today_fmt': _Opt(None, 'env', frozenset((str,))),
'language': _Opt('en', 'env', frozenset((str,))),
'locale_dirs': _Opt(['locales'], 'env', ()),
'locale_dirs': _Opt(['locales'], 'env', frozenset((list, tuple))),
'figure_language_filename': _Opt(
'{root}.{language}{ext}', 'env', frozenset((str,))
),
'gettext_allow_fuzzy_translations': _Opt(False, 'gettext', ()),
'gettext_allow_fuzzy_translations': _Opt(False, 'gettext', frozenset((bool,))),
'translation_progress_classes': _Opt(
False, 'env', ENUM(True, False, 'translated', 'untranslated')
),
'master_doc': _Opt('index', 'env', ()),
'root_doc': _Opt(lambda config: config.master_doc, 'env', ()),
'master_doc': _Opt('index', 'env', frozenset((str,))),
'root_doc': _Opt(lambda config: config.master_doc, 'env', frozenset((str,))),
# ``source_suffix`` type is actually ``dict[str, str | None]``:
# see ``convert_source_suffix()`` below.
'source_suffix': _Opt({'.rst': 'restructuredtext'}, 'env', Any), # type: ignore[arg-type]
'source_encoding': _Opt('utf-8-sig', 'env', ()),
'source_encoding': _Opt('utf-8-sig', 'env', frozenset((str,))),
'exclude_patterns': _Opt([], 'env', frozenset((str,))),
'include_patterns': _Opt(['**'], 'env', frozenset((str,))),
'default_role': _Opt(None, 'env', frozenset((str,))),
'add_function_parentheses': _Opt(True, 'env', ()),
'add_module_names': _Opt(True, 'env', ()),
'add_function_parentheses': _Opt(True, 'env', frozenset((bool,))),
'add_module_names': _Opt(True, 'env', frozenset((bool,))),
'toc_object_entries': _Opt(True, 'env', frozenset((bool,))),
'toc_object_entries_show_parents': _Opt(
'domain', 'env', ENUM('domain', 'all', 'hide')
),
'trim_footnote_reference_space': _Opt(False, 'env', ()),
'show_authors': _Opt(False, 'env', ()),
'trim_footnote_reference_space': _Opt(False, 'env', frozenset((bool,))),
'show_authors': _Opt(False, 'env', frozenset((bool,))),
'pygments_style': _Opt(None, 'html', frozenset((str,))),
'highlight_language': _Opt('default', 'env', ()),
'highlight_options': _Opt({}, 'env', ()),
'templates_path': _Opt([], 'html', ()),
'highlight_language': _Opt('default', 'env', frozenset((str,))),
'highlight_options': _Opt({}, 'env', frozenset((dict,))),
'templates_path': _Opt([], 'html', frozenset((list,))),
'template_bridge': _Opt(None, 'html', frozenset((str,))),
'keep_warnings': _Opt(False, 'env', ()),
'suppress_warnings': _Opt([], 'env', ()),
'keep_warnings': _Opt(False, 'env', frozenset((bool,))),
'suppress_warnings': _Opt([], 'env', frozenset((list, tuple))),
'show_warning_types': _Opt(True, 'env', frozenset((bool,))),
'modindex_common_prefix': _Opt([], 'html', ()),
'modindex_common_prefix': _Opt([], 'html', frozenset((list, tuple))),
'rst_epilog': _Opt(None, 'env', frozenset((str,))),
'rst_prolog': _Opt(None, 'env', frozenset((str,))),
'trim_doctest_flags': _Opt(True, 'env', ()),
'trim_doctest_flags': _Opt(True, 'env', frozenset((bool,))),
'primary_domain': _Opt('py', 'env', frozenset((types.NoneType,))),
'needs_sphinx': _Opt(None, '', frozenset((str,))),
'needs_extensions': _Opt({}, '', ()),
'manpages_url': _Opt(None, 'env', ()),
'nitpicky': _Opt(False, '', ()),
'needs_extensions': _Opt({}, '', frozenset((dict,))),
'manpages_url': _Opt(None, 'env', frozenset((str, types.NoneType))),
'nitpicky': _Opt(False, '', frozenset((bool,))),
'nitpick_ignore': _Opt([], '', frozenset((set, list, tuple))),
'nitpick_ignore_regex': _Opt([], '', frozenset((set, list, tuple))),
'numfig': _Opt(False, 'env', ()),
'numfig_secnum_depth': _Opt(1, 'env', ()),
'numfig': _Opt(False, 'env', frozenset((bool,))),
'numfig_secnum_depth': _Opt(1, 'env', frozenset((int, types.NoneType))),
# numfig_format will be initialized in init_numfig_format()
'numfig_format': _Opt({}, 'env', ()),
'numfig_format': _Opt({}, 'env', frozenset((dict,))),
'maximum_signature_line_length': _Opt(
None, 'env', frozenset((int, types.NoneType))
),
'math_number_all': _Opt(False, 'env', ()),
'math_number_all': _Opt(False, 'env', frozenset((bool,))),
'math_eqref_format': _Opt(None, 'env', frozenset((str,))),
'math_numfig': _Opt(True, 'env', ()),
'math_numfig': _Opt(True, 'env', frozenset((bool,))),
'math_numsep': _Opt('.', 'env', frozenset((str,))),
'tls_verify': _Opt(True, 'env', ()),
'tls_cacerts': _Opt(None, 'env', ()),
'tls_verify': _Opt(True, 'env', frozenset((bool,))),
'tls_cacerts': _Opt(None, 'env', frozenset((str, dict, types.NoneType))),
'user_agent': _Opt(None, 'env', frozenset((str,))),
'smartquotes': _Opt(True, 'env', ()),
'smartquotes_action': _Opt('qDe', 'env', ()),
'smartquotes': _Opt(True, 'env', frozenset((bool,))),
'smartquotes_action': _Opt('qDe', 'env', frozenset((str,))),
'smartquotes_excludes': _Opt(
{'languages': ['ja', 'zh_CN', 'zh_TW'], 'builders': ['man', 'text']},
'env',
(),
frozenset((dict,)),
),
'option_emphasise_placeholders': _Opt(False, 'env', ()),
'option_emphasise_placeholders': _Opt(False, 'env', frozenset((bool,))),
}
def __init__(
@@ -576,7 +576,7 @@ class Config:
def __setstate__(self, state: dict[str, Any]) -> None:
self._overrides = {}
self._options = {
name: _Opt(real_value, rebuild, ())
name: _Opt(real_value, rebuild, frozenset())
for name, (real_value, rebuild) in state.pop('_options').items()
}
self._raw_config = {}
@@ -620,9 +620,9 @@ def eval_config_file(
def _validate_valid_types(
valid_types: type | Collection[type] | ENUM, /
) -> tuple[()] | tuple[type, ...] | frozenset[type] | ENUM:
) -> frozenset[type] | ENUM:
if not valid_types:
return ()
return frozenset()
if isinstance(valid_types, frozenset | ENUM):
return valid_types
if isinstance(valid_types, type):
@@ -631,16 +631,11 @@ def _validate_valid_types(
return frozenset({Any}) # type: ignore[arg-type]
if isinstance(valid_types, set):
return frozenset(valid_types)
if not isinstance(valid_types, tuple):
try:
valid_types = tuple(valid_types)
except TypeError:
logger.warning(__('Failed to convert %r to a set or tuple'), valid_types)
return valid_types # type: ignore[return-value]
try:
return frozenset(valid_types)
except TypeError:
return valid_types
logger.warning(__('Failed to convert %r to a frozenset'), valid_types)
return frozenset()
def convert_source_suffix(app: Sphinx, config: Config) -> None:
@@ -822,6 +817,10 @@ def check_confval_types(app: Sphinx | None, config: Config) -> None:
continue
if type_value in valid_types: # check explicitly listed types
if frozenset in valid_types and type_value in {list, tuple, set}:
setattr(config, name, frozenset(value))
elif tuple in valid_types and type_value is list:
setattr(config, name, tuple(value))
continue
common_bases = {*type_value.__bases__, type_value} & set(type_default.__bases__)

4
sphinx/directives/__init__.py
View File

@@ -364,7 +364,9 @@ class DefaultDomain(SphinxDirective):
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value('strip_signature_backslash', False, 'env')
app.add_config_value(
'strip_signature_backslash', False, 'env', types=frozenset({bool})
)
directives.register_directive('default-role', DefaultRole)
directives.register_directive('default-domain', DefaultDomain)
directives.register_directive('describe', ObjectDescription)

8
sphinx/domains/c/__init__.py
View File

@@ -2,6 +2,7 @@
from __future__ import annotations
from types import NoneType
from typing import TYPE_CHECKING
from docutils import nodes
@@ -948,13 +949,16 @@ def setup(app: Sphinx) -> ExtensionMetadata:
'c_paren_attributes', [], 'env', types=frozenset({list, tuple})
)
app.add_config_value(
'c_extra_keywords', _macro_keywords, 'env', types=frozenset({set, list})
'c_extra_keywords',
_macro_keywords,
'env',
types=frozenset({frozenset, list, set, tuple}),
)
app.add_config_value(
'c_maximum_signature_line_length',
None,
'env',
types=frozenset({int, type(None)}),
types=frozenset({int, NoneType}),
)
app.add_post_transform(AliasTransform)

9
sphinx/domains/cpp/__init__.py
View File

@@ -3,6 +3,7 @@
from __future__ import annotations
import re
from types import NoneType
from typing import TYPE_CHECKING
from docutils import nodes
@@ -1300,7 +1301,7 @@ class CPPDomain(Domain):
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_domain(CPPDomain)
app.add_config_value('cpp_index_common_prefix', [], 'env')
app.add_config_value('cpp_index_common_prefix', [], 'env', types=frozenset({list}))
app.add_config_value('cpp_id_attributes', [], 'env', types=frozenset({list, tuple}))
app.add_config_value(
'cpp_paren_attributes', [], 'env', types=frozenset({list, tuple})
@@ -1309,13 +1310,13 @@ def setup(app: Sphinx) -> ExtensionMetadata:
'cpp_maximum_signature_line_length',
None,
'env',
types=frozenset({int, type(None)}),
types=frozenset({int, NoneType}),
)
app.add_post_transform(AliasTransform)
# debug stuff
app.add_config_value('cpp_debug_lookup', False, '')
app.add_config_value('cpp_debug_show_tree', False, '')
app.add_config_value('cpp_debug_lookup', False, '', types=frozenset({bool}))
app.add_config_value('cpp_debug_show_tree', False, '', types=frozenset({bool}))
def init_stuff(app: Sphinx) -> None:
Symbol.debug_lookup = app.config.cpp_debug_lookup

3
sphinx/domains/javascript.py
View File

@@ -3,6 +3,7 @@
from __future__ import annotations
import contextlib
from types import NoneType
from typing import TYPE_CHECKING
from docutils import nodes
@@ -574,7 +575,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
'javascript_maximum_signature_line_length',
None,
'env',
types=frozenset({int, type(None)}),
types=frozenset({int, NoneType}),
)
app.add_config_value(
'javascript_trailing_comma_in_multi_line_signatures',

11
sphinx/domains/python/__init__.py
View File

@@ -5,6 +5,7 @@ from __future__ import annotations
import builtins
import inspect
import typing
from types import NoneType
from typing import TYPE_CHECKING, NamedTuple, cast
from docutils import nodes
@@ -1108,12 +1109,14 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.setup_extension('sphinx.directives')
app.add_domain(PythonDomain)
app.add_config_value('python_use_unqualified_type_names', False, 'env')
app.add_config_value(
'python_use_unqualified_type_names', False, 'env', types=frozenset({bool})
)
app.add_config_value(
'python_maximum_signature_line_length',
None,
'env',
types=frozenset({int, type(None)}),
types=frozenset({int, NoneType}),
)
app.add_config_value(
'python_trailing_comma_in_multi_line_signatures',
@@ -1121,7 +1124,9 @@ def setup(app: Sphinx) -> ExtensionMetadata:
'env',
types=frozenset({bool}),
)
app.add_config_value('python_display_short_literal_types', False, 'env')
app.add_config_value(
'python_display_short_literal_types', False, 'env', types=frozenset({bool})
)
app.connect('object-description-transform', filter_meta_fields)
app.connect('missing-reference', builtin_resolver, priority=900)

18
sphinx/ext/autodoc/__init__.py
View File

@@ -3174,9 +3174,13 @@ def setup(app: Sphinx) -> ExtensionMetadata:
'env',
types=ENUM('mixed', 'separated'),
)
app.add_config_value('autodoc_default_options', {}, 'env')
app.add_config_value('autodoc_docstring_signature', True, 'env')
app.add_config_value('autodoc_mock_imports', [], 'env')
app.add_config_value('autodoc_default_options', {}, 'env', types=frozenset({dict}))
app.add_config_value(
'autodoc_docstring_signature', True, 'env', types=frozenset({bool})
)
app.add_config_value(
'autodoc_mock_imports', [], 'env', types=frozenset({list, tuple})
)
app.add_config_value(
'autodoc_typehints',
'signature',
@@ -3189,15 +3193,17 @@ def setup(app: Sphinx) -> ExtensionMetadata:
'env',
types=ENUM('all', 'documented', 'documented_params'),
)
app.add_config_value('autodoc_type_aliases', {}, 'env')
app.add_config_value('autodoc_type_aliases', {}, 'env', types=frozenset({dict}))
app.add_config_value(
'autodoc_typehints_format',
'short',
'env',
types=ENUM('fully-qualified', 'short'),
)
app.add_config_value('autodoc_warningiserror', True, 'env')
app.add_config_value('autodoc_inherit_docstrings', True, 'env')
app.add_config_value('autodoc_warningiserror', True, 'env', types=frozenset({bool}))
app.add_config_value(
'autodoc_inherit_docstrings', True, 'env', types=frozenset({bool})
)
app.add_event('autodoc-before-process-signature')
app.add_event('autodoc-process-docstring')
app.add_event('autodoc-process-signature')

4
sphinx/ext/autodoc/preserve_defaults.py
View File

@@ -197,7 +197,9 @@ def update_defvalue(app: Sphinx, obj: Any, bound_method: bool) -> None:
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value('autodoc_preserve_defaults', False, 'env')
app.add_config_value(
'autodoc_preserve_defaults', False, 'env', types=frozenset({bool})
)
app.connect('autodoc-before-process-signature', update_defvalue)
return {

9
sphinx/ext/autosectionlabel.py
View File

@@ -2,6 +2,7 @@
from __future__ import annotations
from types import NoneType
from typing import TYPE_CHECKING, cast
from docutils import nodes
@@ -70,8 +71,12 @@ def register_sections_as_label(app: Sphinx, document: Node) -> None:
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value('autosectionlabel_prefix_document', False, 'env')
app.add_config_value('autosectionlabel_maxdepth', None, 'env')
app.add_config_value(
'autosectionlabel_prefix_document', False, 'env', types=frozenset({bool})
)
app.add_config_value(
'autosectionlabel_maxdepth', None, 'env', types=frozenset({int, NoneType})
)
app.connect('doctree-read', register_sections_as_label)
return {

15
sphinx/ext/autosummary/__init__.py
View File

@@ -957,14 +957,21 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_directive('autosummary', Autosummary)
app.add_role('autolink', AutoLink())
app.connect('builder-inited', process_generate_options)
app.add_config_value('autosummary_context', {}, 'env')
app.add_config_value('autosummary_filename_map', {}, 'html')
app.add_config_value('autosummary_context', {}, 'env', types=frozenset({dict}))
app.add_config_value(
'autosummary_filename_map', {}, 'html', types=frozenset({dict})
)
app.add_config_value(
'autosummary_generate', True, 'env', types=frozenset({bool, list})
)
app.add_config_value('autosummary_generate_overwrite', True, '')
app.add_config_value(
'autosummary_mock_imports', lambda config: config.autodoc_mock_imports, 'env'
'autosummary_generate_overwrite', True, '', types=frozenset({bool})
)
app.add_config_value(
'autosummary_mock_imports',
lambda config: config.autodoc_mock_imports,
'env',
types=frozenset({list, tuple}),
)
app.add_config_value(
'autosummary_imported_members', False, '', types=frozenset({bool})

34
sphinx/ext/coverage.py
View File

@@ -522,23 +522,35 @@ class CoverageBuilder(Builder):
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(CoverageBuilder)
app.add_config_value('coverage_modules', (), '', types=frozenset({tuple, list}))
app.add_config_value('coverage_ignore_modules', [], '')
app.add_config_value('coverage_ignore_functions', [], '')
app.add_config_value('coverage_ignore_classes', [], '')
app.add_config_value('coverage_ignore_pyobjects', [], '')
app.add_config_value('coverage_c_path', [], '')
app.add_config_value('coverage_c_regexes', {}, '')
app.add_config_value('coverage_ignore_c_items', {}, '')
app.add_config_value('coverage_write_headline', True, '')
app.add_config_value('coverage_modules', (), '', types=frozenset({list, tuple}))
app.add_config_value(
'coverage_ignore_modules', [], '', types=frozenset({list, tuple})
)
app.add_config_value(
'coverage_ignore_functions', [], '', types=frozenset({list, tuple})
)
app.add_config_value(
'coverage_ignore_classes', [], '', types=frozenset({list, tuple})
)
app.add_config_value(
'coverage_ignore_pyobjects', [], '', types=frozenset({list, tuple})
)
app.add_config_value('coverage_c_path', [], '', types=frozenset({list, tuple}))
app.add_config_value('coverage_c_regexes', {}, '', types=frozenset({dict}))
app.add_config_value('coverage_ignore_c_items', {}, '', types=frozenset({dict}))
app.add_config_value('coverage_write_headline', True, '', types=frozenset({bool}))
app.add_config_value(
'coverage_statistics_to_report', True, '', types=frozenset({bool})
)
app.add_config_value(
'coverage_statistics_to_stdout', True, '', types=frozenset({bool})
)
app.add_config_value('coverage_skip_undoc_in_source', False, '')
app.add_config_value('coverage_show_missing_items', False, '')
app.add_config_value(
'coverage_skip_undoc_in_source', False, '', types=frozenset({bool})
)
app.add_config_value(
'coverage_show_missing_items', False, '', types=frozenset({bool})
)
return {
'version': sphinx.__display_version__,
'parallel_read_safe': True,

11
sphinx/ext/doctest.py
View File

@@ -624,16 +624,19 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_builder(DocTestBuilder)
# this config value adds to sys.path
app.add_config_value('doctest_show_successes', True, '', types=frozenset({bool}))
app.add_config_value('doctest_path', (), '')
app.add_config_value('doctest_test_doctest_blocks', 'default', '')
app.add_config_value('doctest_global_setup', '', '')
app.add_config_value('doctest_global_cleanup', '', '')
app.add_config_value('doctest_path', (), '', types=frozenset({list, tuple}))
app.add_config_value(
'doctest_test_doctest_blocks', 'default', '', types=frozenset({str})
)
app.add_config_value('doctest_global_setup', '', '', types=frozenset({str}))
app.add_config_value('doctest_global_cleanup', '', '', types=frozenset({str}))
app.add_config_value(
'doctest_default_flags',
doctest.DONT_ACCEPT_TRUE_FOR_1
| doctest.ELLIPSIS
| doctest.IGNORE_EXCEPTION_DETAIL,
'',
types=frozenset({int}),
)
return {
'version': sphinx.__display_version__,

6
sphinx/ext/extlinks.py
View File

@@ -126,8 +126,10 @@ def setup_link_roles(app: Sphinx) -> None:
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value('extlinks', {}, 'env')
app.add_config_value('extlinks_detect_hardcoded_links', False, 'env')
app.add_config_value('extlinks', {}, 'env', types=frozenset({dict}))
app.add_config_value(
'extlinks_detect_hardcoded_links', False, 'env', types=frozenset({bool})
)
app.connect('builder-inited', setup_link_roles)
app.add_post_transform(ExternalLinksChecker)

10
sphinx/ext/graphviz.py
View File

@@ -522,9 +522,13 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_directive('graphviz', Graphviz)
app.add_directive('graph', GraphvizSimple)
app.add_directive('digraph', GraphvizSimple)
app.add_config_value('graphviz_dot', 'dot', 'html')
app.add_config_value('graphviz_dot_args', (), 'html')
app.add_config_value('graphviz_output_format', 'png', 'html')
app.add_config_value('graphviz_dot', 'dot', 'html', types=frozenset({str}))
app.add_config_value(
'graphviz_dot_args', (), 'html', types=frozenset({list, tuple})
)
app.add_config_value(
'graphviz_output_format', 'png', 'html', types=frozenset({str})
)
app.add_css_file('graphviz.css')
app.connect('config-inited', on_config_inited)
return {

14
sphinx/ext/imgconverter.py
View File

@@ -97,14 +97,20 @@ def setup(app: Sphinx) -> ExtensionMetadata:
if sys.platform == 'win32':
# On Windows, we use Imagemagik v7 by default to avoid the trouble for
# convert.exe bundled with Windows.
app.add_config_value('image_converter', 'magick', 'env')
app.add_config_value('image_converter_args', ['convert'], 'env')
app.add_config_value('image_converter', 'magick', 'env', types=frozenset({str}))
app.add_config_value(
'image_converter_args', ['convert'], 'env', types=frozenset({list, tuple})
)
else:
# On other platform, we use Imagemagick v6 by default. Especially,
# Debian/Ubuntu are still based of v6. So we can't use "magick" command
# for these platforms.
app.add_config_value('image_converter', 'convert', 'env')
app.add_config_value('image_converter_args', [], 'env')
app.add_config_value(
'image_converter', 'convert', 'env', types=frozenset({str})
)
app.add_config_value(
'image_converter_args', [], 'env', types=frozenset({list, tuple})
)
return {
'version': sphinx.__display_version__,

25
sphinx/ext/imgmath.py
View File

@@ -411,21 +411,26 @@ def setup(app: Sphinx) -> ExtensionMetadata:
block_renderers=(html_visit_displaymath, None),
)
app.add_config_value('imgmath_image_format', 'png', 'html')
app.add_config_value('imgmath_dvipng', 'dvipng', 'html')
app.add_config_value('imgmath_dvisvgm', 'dvisvgm', 'html')
app.add_config_value('imgmath_latex', 'latex', 'html')
app.add_config_value('imgmath_use_preview', False, 'html')
app.add_config_value('imgmath_image_format', 'png', 'html', types=frozenset({str}))
app.add_config_value('imgmath_dvipng', 'dvipng', 'html', types=frozenset({str}))
app.add_config_value('imgmath_dvisvgm', 'dvisvgm', 'html', types=frozenset({str}))
app.add_config_value('imgmath_latex', 'latex', 'html', types=frozenset({str}))
app.add_config_value('imgmath_use_preview', False, 'html', types=frozenset({bool}))
app.add_config_value(
'imgmath_dvipng_args',
['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'],
'html',
types=frozenset({list}),
)
app.add_config_value('imgmath_dvisvgm_args', ['--no-fonts'], 'html')
app.add_config_value('imgmath_latex_args', [], 'html')
app.add_config_value('imgmath_latex_preamble', '', 'html')
app.add_config_value('imgmath_add_tooltips', True, 'html')
app.add_config_value('imgmath_font_size', 12, 'html')
app.add_config_value(
'imgmath_dvisvgm_args', ['--no-fonts'], 'html', types=frozenset({list, tuple})
)
app.add_config_value(
'imgmath_latex_args', [], 'html', types=frozenset({list, tuple})
)
app.add_config_value('imgmath_latex_preamble', '', 'html', types=frozenset({str}))
app.add_config_value('imgmath_add_tooltips', True, 'html', types=frozenset({bool}))
app.add_config_value('imgmath_font_size', 12, 'html', types=frozenset({int}))
app.add_config_value('imgmath_embed', False, 'html', types=frozenset({bool}))
app.connect('build-finished', clean_up_files)
return {

8
sphinx/ext/inheritance_diagram.py
View File

@@ -558,10 +558,10 @@ def setup(app: Sphinx) -> ExtensionMetadata:
texinfo=(texinfo_visit_inheritance_diagram, None),
)
app.add_directive('inheritance-diagram', InheritanceDiagram)
app.add_config_value('inheritance_graph_attrs', {}, '')
app.add_config_value('inheritance_node_attrs', {}, '')
app.add_config_value('inheritance_edge_attrs', {}, '')
app.add_config_value('inheritance_alias', {}, '')
app.add_config_value('inheritance_graph_attrs', {}, '', types=frozenset({dict}))
app.add_config_value('inheritance_node_attrs', {}, '', types=frozenset({dict}))
app.add_config_value('inheritance_edge_attrs', {}, '', types=frozenset({dict}))
app.add_config_value('inheritance_alias', {}, '', types=frozenset({dict}))
return {
'version': sphinx.__display_version__,
'parallel_read_safe': True,

3
sphinx/ext/intersphinx/__init__.py
View File

@@ -35,6 +35,7 @@ __all__ = (
'validate_intersphinx_mapping',
)
from types import NoneType
from typing import TYPE_CHECKING
import sphinx
@@ -67,7 +68,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value('intersphinx_resolve_self', '', 'env', types=frozenset({str}))
app.add_config_value('intersphinx_cache_limit', 5, '', types=frozenset({int}))
app.add_config_value(
'intersphinx_timeout', None, '', types=frozenset({int, float, type(None)})
'intersphinx_timeout', None, '', types=frozenset({float, int, NoneType})
)
app.add_config_value(
'intersphinx_disabled_reftypes',

5
sphinx/ext/linkcode.py
View File

@@ -2,6 +2,7 @@
from __future__ import annotations
from types import FunctionType, NoneType
from typing import TYPE_CHECKING
from docutils import nodes
@@ -90,7 +91,9 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
def setup(app: Sphinx) -> ExtensionMetadata:
app.connect('doctree-read', doctree_read)
app.add_config_value('linkcode_resolve', None, '')
app.add_config_value(
'linkcode_resolve', None, '', types=frozenset({FunctionType, NoneType})
)
return {
'version': sphinx.__display_version__,
'parallel_read_safe': True,

28
sphinx/ext/mathjax.py
View File

@@ -8,6 +8,7 @@ This requires the MathJax JavaScript library on your webserver/computer.
from __future__ import annotations
import json
from types import NoneType
from typing import TYPE_CHECKING, cast
from docutils import nodes
@@ -128,13 +129,26 @@ def setup(app: Sphinx) -> ExtensionMetadata:
block_renderers=(html_visit_displaymath, None),
)
app.add_config_value('mathjax_path', MATHJAX_URL, 'html')
app.add_config_value('mathjax_options', {}, 'html')
app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html')
app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html')
app.add_config_value('mathjax_config', None, 'html')
app.add_config_value('mathjax2_config', lambda c: c.mathjax_config, 'html')
app.add_config_value('mathjax3_config', None, 'html')
app.add_config_value('mathjax_path', MATHJAX_URL, 'html', types=frozenset({str}))
app.add_config_value('mathjax_options', {}, 'html', types=frozenset({dict}))
app.add_config_value(
'mathjax_inline', [r'\(', r'\)'], 'html', types=frozenset({list, tuple})
)
app.add_config_value(
'mathjax_display', [r'\[', r'\]'], 'html', types=frozenset({list, tuple})
)
app.add_config_value(
'mathjax_config', None, 'html', types=frozenset({dict, NoneType})
)
app.add_config_value(
'mathjax2_config',
lambda c: c.mathjax_config,
'html',
types=frozenset({dict, NoneType}),
)
app.add_config_value(
'mathjax3_config', None, 'html', types=frozenset({dict, NoneType})
)
app.connect('html-page-context', install_mathjax)
return {

6
sphinx/ext/napoleon/__init__.py
View File

@@ -2,6 +2,7 @@
from __future__ import annotations
from types import NoneType
from typing import TYPE_CHECKING
import sphinx
@@ -331,7 +332,10 @@ def setup(app: Sphinx) -> ExtensionMetadata:
app.connect('autodoc-skip-member', _skip_member)
for name, (default, rebuild) in Config._config_values.items():
app.add_config_value(name, default, rebuild)
if isinstance(default, bool):
app.add_config_value(name, default, rebuild, types=frozenset({bool}))
else:
app.add_config_value(name, default, rebuild, types=frozenset({NoneType}))
return {
'version': sphinx.__display_version__,
'parallel_read_safe': True,

6
sphinx/ext/todo.py
View File

@@ -225,9 +225,9 @@ def latex_depart_todo_node(self: LaTeXTranslator, node: todo_node) -> None:
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_event('todo-defined')
app.add_config_value('todo_include_todos', False, 'html')
app.add_config_value('todo_link_only', False, 'html')
app.add_config_value('todo_emit_warnings', False, 'html')
app.add_config_value('todo_include_todos', False, 'html', types=frozenset({bool}))
app.add_config_value('todo_link_only', False, 'html', types=frozenset({bool}))
app.add_config_value('todo_emit_warnings', False, 'html', types=frozenset({bool}))
app.add_node(todolist)
app.add_node(

17
sphinx/ext/viewcode.py
View File

@@ -6,6 +6,7 @@ import importlib.util
import operator
import posixpath
import traceback
from types import NoneType
from typing import TYPE_CHECKING, cast
from docutils import nodes
@@ -382,16 +383,22 @@ def collect_pages(app: Sphinx) -> Iterator[tuple[str, dict[str, Any], str]]:
def setup(app: Sphinx) -> ExtensionMetadata:
app.add_config_value('viewcode_import', None, '')
app.add_config_value('viewcode_enable_epub', False, '')
app.add_config_value('viewcode_follow_imported_members', True, '')
app.add_config_value('viewcode_import', None, '', types=frozenset({NoneType}))
app.add_config_value('viewcode_enable_epub', False, '', types=frozenset({bool}))
app.add_config_value(
'viewcode_follow_imported_members', True, '', types=frozenset({bool})
)
app.add_config_value('viewcode_line_numbers', False, 'env', types=frozenset({bool}))
app.connect('doctree-read', doctree_read)
app.connect('env-merge-info', env_merge_info)
app.connect('env-purge-doc', env_purge_doc)
app.connect('html-collect-pages', collect_pages)
# app.add_config_value('viewcode_include_modules', [], 'env')
# app.add_config_value('viewcode_exclude_modules', [], 'env')
# app.add_config_value(
# 'viewcode_include_modules', [], 'env', types=frozenset({list, tuple})
# )
# app.add_config_value(
# 'viewcode_exclude_modules', [], 'env', types=frozenset({list, tuple})
# )
app.add_event('viewcode-find-source')
app.add_event('viewcode-follow-imported')
app.add_post_transform(ViewcodeAnchorTransform)