diff --git a/docs/lite/api/_custom/sphinx_builder_html b/docs/lite/api/_custom/sphinx_builder_html
index 453a52fea86bbe95cd49a2090bc25b2db53c3901..4bf16bba38d3acc7f7ceb17adf911f052d8d4de1 100644
--- a/docs/lite/api/_custom/sphinx_builder_html
+++ b/docs/lite/api/_custom/sphinx_builder_html
@@ -1,12 +1,6 @@
-"""
-    sphinx.builders.html
-    ~~~~~~~~~~~~~~~~~~~~
+"""Several HTML builders."""
 
-    Several HTML builders.
-
-    :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import html
 import os
@@ -19,11 +13,12 @@ from lxml import etree
 from hashlib import md5
 from datetime import datetime
 from os import path
-from typing import IO, Any, Dict, Iterable, Iterator, List, Set, Tuple, Type
+from typing import IO, Any, Iterable, Iterator, List, Tuple, Type
 from urllib.parse import quote
 
+import docutils.readers.doctree
 from docutils import nodes
-from docutils.core import publish_parts
+from docutils.core import Publisher
 from docutils.frontend import OptionParser
 from docutils.io import DocTreeInput, StringOutput
 from docutils.nodes import Node
@@ -35,6 +30,7 @@ from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import ENUM, Config
 from sphinx.domains import Domain, Index, IndexEntry
+from sphinx.environment import BuildEnvironment
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.environment.adapters.indexentries import IndexEntries
 from sphinx.environment.adapters.toctree import TocTree
@@ -43,22 +39,17 @@ from sphinx.highlighting import PygmentsBridge
 from sphinx.locale import _, __
 from sphinx.search import js_index
 from sphinx.theming import HTMLThemeFactory
-from sphinx.util import isurl, logging, md5, progress_message, status_iterator
-from sphinx.util.docutils import is_html5_writer_available, new_document
+from sphinx.util import isurl, logging, md5
+from sphinx.util.display import progress_message, status_iterator
+from sphinx.util.docutils import new_document
 from sphinx.util.fileutil import copy_asset
 from sphinx.util.i18n import format_date
 from sphinx.util.inventory import InventoryFile
 from sphinx.util.matching import DOTFILES, Matcher, patmatch
 from sphinx.util.osutil import copyfile, ensuredir, os_path, relative_uri
 from sphinx.util.tags import Tags
-from sphinx.writers.html import HTMLTranslator, HTMLWriter
-
-# HTML5 Writer is available or not
-if is_html5_writer_available():
-    from sphinx.writers.html5 import HTML5Translator
-    html5_ready = True
-else:
-    html5_ready = False
+from sphinx.writers.html import HTMLWriter
+from sphinx.writers.html5 import HTML5Translator
 
 #: the filename for the inventory of objects
 INVENTORY_FILENAME = 'objects.inv'
@@ -66,6 +57,17 @@ INVENTORY_FILENAME = 'objects.inv'
 logger = logging.getLogger(__name__)
 return_codes_re = re.compile('[\r\n]+')
 
+DOMAIN_INDEX_TYPE = Tuple[
+    # Index name (e.g. py-modindex)
+    str,
+    # Index class
+    Type[Index],
+    # list of (heading string, list of index entries) pairs.
+    List[Tuple[str, List[IndexEntry]]],
+    # whether sub-entries should start collapsed
+    bool,
+]
+
 
 def get_stable_hash(obj: Any) -> str:
     """
@@ -80,6 +82,17 @@ def get_stable_hash(obj: Any) -> str:
     return md5(str(obj).encode()).hexdigest()
 
 
+def convert_locale_to_language_tag(locale: str | None) -> str | None:
+    """Convert a locale string to a language tag (ex. en_US -> en-US).
+
+    refs: BCP 47 (:rfc:`5646`)
+    """
+    if locale:
+        return locale.replace('_', '-')
+    else:
+        return None
+
+
 class Stylesheet(str):
     """A metadata of stylesheet.
 
@@ -87,12 +100,12 @@ class Stylesheet(str):
     its filename (str).
     """
 
-    attributes: Dict[str, str] = None
+    attributes: dict[str, str] = None
     filename: str = None
     priority: int = None
 
-    def __new__(cls, filename: str, *args: str, priority: int = 500, **attributes: Any
-                ) -> "Stylesheet":
+    def __new__(cls, filename: str, *args: str, priority: int = 500, **attributes: Any,
+                ) -> Stylesheet:
         self = str.__new__(cls, filename)
         self.filename = filename
         self.priority = priority
@@ -113,11 +126,11 @@ class JavaScript(str):
     its filename (str).
     """
 
-    attributes: Dict[str, str] = None
+    attributes: dict[str, str] = None
     filename: str = None
     priority: int = None
 
-    def __new__(cls, filename: str, priority: int = 500, **attributes: str) -> "JavaScript":
+    def __new__(cls, filename: str, priority: int = 500, **attributes: str) -> JavaScript:
         self = str.__new__(cls, filename)
         self.filename = filename
         self.priority = priority
@@ -134,7 +147,7 @@ class BuildInfo:
     """
 
     @classmethod
-    def load(cls, f: IO) -> "BuildInfo":
+    def load(cls, f: IO) -> BuildInfo:
         try:
             lines = f.readlines()
             assert lines[0].rstrip() == '# Sphinx build info version 1'
@@ -148,7 +161,9 @@ class BuildInfo:
         except Exception as exc:
             raise ValueError(__('build info file is broken: %r') % exc) from exc
 
-    def __init__(self, config: Config = None, tags: Tags = None, config_categories: List[str] = []) -> None:  # NOQA
+    def __init__(
+        self, config: Config = None, tags: Tags = None, config_categories: list[str] = [],
+    ) -> None:
         self.config_hash = ''
         self.tags_hash = ''
 
@@ -159,7 +174,7 @@ class BuildInfo:
         if tags:
             self.tags_hash = get_stable_hash(sorted(tags))
 
-    def __eq__(self, other: "BuildInfo") -> bool:  # type: ignore
+    def __eq__(self, other: BuildInfo) -> bool:  # type: ignore
         return (self.config_hash == other.config_hash and
                 self.tags_hash == other.tags_hash)
 
@@ -201,23 +216,39 @@ class StandaloneHTMLBuilder(Builder):
     download_support = True  # enable download role
 
     imgpath: str = None
-    domain_indices: List[Tuple[str, Type[Index], List[Tuple[str, List[IndexEntry]]], bool]] = []  # NOQA
+    domain_indices: list[DOMAIN_INDEX_TYPE] = []
 
-    def __init__(self, app: Sphinx) -> None:
-        super().__init__(app)
+    def __init__(self, app: Sphinx, env: BuildEnvironment = None) -> None:
+        super().__init__(app, env)
 
         # CSS files
-        self.css_files: List[Stylesheet] = []
+        self.css_files: list[Stylesheet] = []
 
         # JS files
-        self.script_files: List[JavaScript] = []
+        self.script_files: list[JavaScript] = []
+
+        # Cached Publisher for writing doctrees to HTML
+        reader = docutils.readers.doctree.Reader(parser_name='restructuredtext')
+        pub = Publisher(
+            reader=reader,
+            parser=reader.parser,
+            writer=HTMLWriter(self),
+            source_class=DocTreeInput,
+            destination=StringOutput(encoding='unicode'),
+        )
+        if docutils.__version_info__[:2] >= (0, 19):
+            pub.get_settings(output_encoding='unicode', traceback=True)
+        else:
+            op = pub.setup_option_parser(output_encoding='unicode', traceback=True)
+            pub.settings = op.get_default_values()
+        self._publisher = pub
 
     def init(self) -> None:
         self.build_info = self.create_build_info()
         # basename of images directory
         self.imagedir = '_images'
         # section numbers for headings in the currently visited document
-        self.secnumbers: Dict[str, Tuple[int, ...]] = {}
+        self.secnumbers: dict[str, tuple[int, ...]] = {}
         # currently written docname
         self.current_docname: str = None
 
@@ -255,15 +286,18 @@ class StandaloneHTMLBuilder(Builder):
                 return jsfile
         return None
 
-    def _get_style_filename(self) -> str:
-        if self.config.html_style is not None:
-            return self.config.html_style
+    def _get_style_filenames(self) -> Iterator[str]:
+        if isinstance(self.config.html_style, str):
+            yield self.config.html_style
+        elif self.config.html_style is not None:
+            yield from self.config.html_style
         elif self.theme:
-            return self.theme.get_config('theme', 'stylesheet')
+            stylesheet = self.theme.get_config('theme', 'stylesheet')
+            yield from map(str.strip, stylesheet.split(','))
         else:
-            return 'default.css'
+            yield 'default.css'
 
-    def get_theme_config(self) -> Tuple[str, Dict]:
+    def get_theme_config(self) -> tuple[str, dict]:
         return self.config.html_theme, self.config.html_theme_options
 
     def init_templates(self) -> None:
@@ -300,7 +334,9 @@ class StandaloneHTMLBuilder(Builder):
     def init_css_files(self) -> None:
         self.css_files = []
         self.add_css_file('pygments.css', priority=200)
-        self.add_css_file(self._get_style_filename(), priority=200)
+
+        for filename in self._get_style_filenames():
+            self.add_css_file(filename, priority=200)
 
         for filename, attrs in self.app.registry.css_files:
             self.add_css_file(filename, **attrs)
@@ -319,9 +355,8 @@ class StandaloneHTMLBuilder(Builder):
         self.script_files = []
         self.add_js_file('documentation_options.js', id="documentation_options",
                          data_url_root='', priority=200)
-        self.add_js_file('jquery.js', priority=200)
-        self.add_js_file('underscore.js', priority=200)
         self.add_js_file('doctools.js', priority=200)
+        self.add_js_file('sphinx_highlight.js', priority=200)
 
         for filename, attrs in self.app.registry.js_files:
             self.add_js_file(filename, **attrs)
@@ -330,7 +365,7 @@ class StandaloneHTMLBuilder(Builder):
             attrs.setdefault('priority', 800)  # User's JSs are loaded after extensions'
             self.add_js_file(filename, **attrs)
 
-        if self.config.language and self._get_translations_js():
+        if self._get_translations_js():
             self.add_js_file('translations.js')
 
     def add_js_file(self, filename: str, **kwargs: Any) -> None:
@@ -340,11 +375,8 @@ class StandaloneHTMLBuilder(Builder):
         self.script_files.append(JavaScript(filename, **kwargs))
 
     @property
-    def default_translator_class(self) -> Type[nodes.NodeVisitor]:  # type: ignore
-        if not html5_ready or self.config.html4_writer:
-            return HTMLTranslator
-        else:
-            return HTML5Translator
+    def default_translator_class(self) -> type[nodes.NodeVisitor]:  # type: ignore
+        return HTML5Translator
 
     @property
     def math_renderer_name(self) -> str:
@@ -368,7 +400,7 @@ class StandaloneHTMLBuilder(Builder):
 
     def get_outdated_docs(self) -> Iterator[str]:
         try:
-            with open(path.join(self.outdir, '.buildinfo')) as fp:
+            with open(path.join(self.outdir, '.buildinfo'), encoding="utf-8") as fp:
                 buildinfo = BuildInfo.load(fp)
 
             if self.build_info != buildinfo:
@@ -412,41 +444,40 @@ class StandaloneHTMLBuilder(Builder):
                 # source doesn't exist anymore
                 pass
 
-    def get_asset_paths(self) -> List[str]:
+    def get_asset_paths(self) -> list[str]:
         return self.config.html_extra_path + self.config.html_static_path
 
-    def render_partial(self, node: Node) -> Dict[str, str]:
+    def render_partial(self, node: Node | None) -> dict[str, str]:
         """Utility: Render a lone doctree node."""
         if node is None:
             return {'fragment': ''}
+
         doc = new_document('<partial node>')
         doc.append(node)
+        self._publisher.set_source(doc)
+        self._publisher.publish()
+        return self._publisher.writer.parts
 
-        writer = HTMLWriter(self)
-        return publish_parts(reader_name='doctree',
-                             writer=writer,
-                             source_class=DocTreeInput,
-                             settings_overrides={'output_encoding': 'unicode'},
-                             source=doc)
-
-    def prepare_writing(self, docnames: Set[str]) -> None:
+    def prepare_writing(self, docnames: set[str]) -> None:
         # create the search indexer
         self.indexer = None
         if self.search:
             from sphinx.search import IndexBuilder
             lang = self.config.html_search_language or self.config.language
-            if not lang:
-                lang = 'en'
             self.indexer = IndexBuilder(self.env, lang,
                                         self.config.html_search_options,
                                         self.config.html_search_scorer)
             self.load_indexer(docnames)
 
         self.docwriter = HTMLWriter(self)
-        self.docsettings: Any = OptionParser(
-            defaults=self.env.settings,
-            components=(self.docwriter,),
-            read_config_files=True).get_default_values()
+        with warnings.catch_warnings():
+            warnings.filterwarnings('ignore', category=DeprecationWarning)
+            # DeprecationWarning: The frontend.OptionParser class will be replaced
+            # by a subclass of argparse.ArgumentParser in Docutils 0.21 or later.
+            self.docsettings: Any = OptionParser(
+                defaults=self.env.settings,
+                components=(self.docwriter,),
+                read_config_files=True).get_default_values()
         self.docsettings.compact_lists = bool(self.config.html_compact_lists)
 
         # determine the additional indices to include
@@ -457,7 +488,7 @@ class StandaloneHTMLBuilder(Builder):
             for domain_name in sorted(self.env.domains):
                 domain: Domain = self.env.domains[domain_name]
                 for indexcls in domain.indices:
-                    indexname = '%s-%s' % (domain.name, indexcls.name)
+                    indexname = f'{domain.name}-{indexcls.name}'
                     if isinstance(indices_config, list):
                         if indexname not in indices_config:
                             continue
@@ -487,7 +518,7 @@ class StandaloneHTMLBuilder(Builder):
 
         self.relations = self.env.collect_relations()
 
-        rellinks: List[Tuple[str, str, str, str]] = []
+        rellinks: list[tuple[str, str, str, str]] = []
         if self.use_index:
             rellinks.append(('genindex', _('General Index'), 'I', _('index')))
         for indexname, indexcls, _content, _collapse in self.domain_indices:
@@ -499,6 +530,7 @@ class StandaloneHTMLBuilder(Builder):
         # back up script_files and css_files to allow adding JS/CSS files to a specific page.
         self._script_files = list(self.script_files)
         self._css_files = list(self.css_files)
+        styles = list(self._get_style_filenames())
 
         self.globalcontext = {
             'embedded': self.embedded,
@@ -513,6 +545,7 @@ class StandaloneHTMLBuilder(Builder):
             'docstitle': self.config.html_title,
             'shorttitle': self.config.html_short_title,
             'show_copyright': self.config.html_show_copyright,
+            'show_search_summary': self.config.html_show_search_summary,
             'show_sphinx': self.config.html_show_sphinx,
             'has_source': self.config.html_copy_source,
             'show_source': self.config.html_show_sourcelink,
@@ -520,17 +553,18 @@ class StandaloneHTMLBuilder(Builder):
             'file_suffix': self.out_suffix,
             'link_suffix': self.link_suffix,
             'script_files': self.script_files,
-            'language': self.config.language,
+            'language': convert_locale_to_language_tag(self.config.language),
             'css_files': self.css_files,
             'sphinx_version': __display_version__,
             'sphinx_version_tuple': sphinx_version,
-            'style': self._get_style_filename(),
+            'docutils_version_info': docutils.__version_info__[:5],
+            'styles': styles,
             'rellinks': rellinks,
             'builder': self.name,
             'parents': [],
-            'logo': logo,
-            'favicon': favicon,
-            'html5_doctype': html5_ready and not self.config.html4_writer,
+            'logo_url': logo,
+            'favicon_url': favicon,
+            'html5_doctype': True,
         }
         if self.theme:
             self.globalcontext.update(
@@ -538,7 +572,7 @@ class StandaloneHTMLBuilder(Builder):
                 self.theme.get_options(self.theme_options).items())
         self.globalcontext.update(self.config.html_context)
 
-    def get_doc_context(self, docname: str, body: str, metatags: str) -> Dict[str, Any]:
+    def get_doc_context(self, docname: str, body: str, metatags: str) -> dict[str, Any]:
         """Collect items for the template context of a page."""
         # find out relations
         prev = next = None
@@ -550,7 +584,7 @@ class StandaloneHTMLBuilder(Builder):
             try:
                 next = {
                     'link': self.get_relative_uri(docname, related[2]),
-                    'title': self.render_partial(titles[related[2]])['title']
+                    'title': self.render_partial(titles[related[2]])['title'],
                 }
                 rellinks.append((related[2], next['title'], 'N', _('next')))
             except KeyError:
@@ -559,7 +593,7 @@ class StandaloneHTMLBuilder(Builder):
             try:
                 prev = {
                     'link': self.get_relative_uri(docname, related[1]),
-                    'title': self.render_partial(titles[related[1]])['title']
+                    'title': self.render_partial(titles[related[1]])['title'],
                 }
                 rellinks.append((related[1], prev['title'], 'P', _('previous')))
             except KeyError:
@@ -762,19 +796,20 @@ class StandaloneHTMLBuilder(Builder):
 
     def create_pygments_style_file(self) -> None:
         """create a style file for pygments."""
-        with open(path.join(self.outdir, '_static', 'pygments.css'), 'w') as f:
+        with open(path.join(self.outdir, '_static', 'pygments.css'), 'w',
+                  encoding="utf-8") as f:
             f.write(self.highlighter.get_stylesheet())
 
         if self.dark_highlighter:
-            with open(path.join(self.outdir, '_static', 'pygments_dark.css'), 'w') as f:
+            with open(path.join(self.outdir, '_static', 'pygments_dark.css'), 'w',
+                      encoding="utf-8") as f:
                 f.write(self.dark_highlighter.get_stylesheet())
 
     def copy_translation_js(self) -> None:
         """Copy a JavaScript file for translations."""
-        if self.config.language is not None:
-            jsfile = self._get_translations_js()
-            if jsfile:
-                copyfile(jsfile, path.join(self.outdir, '_static', 'translations.js'))
+        jsfile = self._get_translations_js()
+        if jsfile:
+            copyfile(jsfile, path.join(self.outdir, '_static', 'translations.js'))
 
     def copy_stemmer_js(self) -> None:
         """Copy a JavaScript file for stemmer."""
@@ -787,7 +822,7 @@ class StandaloneHTMLBuilder(Builder):
                 if jsfile:
                     copyfile(jsfile, path.join(self.outdir, '_static', '_stemmer.js'))
 
-    def copy_theme_static_files(self, context: Dict) -> None:
+    def copy_theme_static_files(self, context: dict[str, Any]) -> None:
         def onerror(filename: str, error: Exception) -> None:
             logger.warning(__('Failed to copy a file in html_static_file: %s: %r'),
                            filename, error)
@@ -799,7 +834,7 @@ class StandaloneHTMLBuilder(Builder):
                            excluded=DOTFILES, context=context,
                            renderer=self.templates, onerror=onerror)
 
-    def copy_html_static_files(self, context: Dict) -> None:
+    def copy_html_static_files(self, context: dict) -> None:
         def onerror(filename: str, error: Exception) -> None:
             logger.warning(__('Failed to copy a file in html_static_file: %s: %r'),
                            filename, error)
@@ -853,7 +888,7 @@ class StandaloneHTMLBuilder(Builder):
 
     def write_buildinfo(self) -> None:
         try:
-            with open(path.join(self.outdir, '.buildinfo'), 'w') as fp:
+            with open(path.join(self.outdir, '.buildinfo'), 'w', encoding="utf-8") as fp:
                 self.build_info.dump(fp)
         except OSError as exc:
             logger.warning(__('Failed to write build info file: %r'), exc)
@@ -867,7 +902,7 @@ class StandaloneHTMLBuilder(Builder):
         """Pick the best candidate for an image and link down-scaled images to
         their high res version.
         """
-        Builder.post_process_images(self, doctree)
+        super().post_process_images(doctree)
 
         if self.config.html_scaled_image_link and self.html_scaled_image_link:
             for node in doctree.findall(nodes.image):
@@ -875,12 +910,13 @@ class StandaloneHTMLBuilder(Builder):
                     # resizing options are not given. scaled image link is available
                     # only for resized images.
                     continue
-                elif isinstance(node.parent, nodes.reference):
+                if isinstance(node.parent, nodes.reference):
                     # A image having hyperlink target
                     continue
-                elif 'no-scaled-link' in node['classes']:
+                if 'no-scaled-link' in node['classes']:
                     # scaled image link is disabled for this node
                     continue
+
                 uri = node['uri']
                 reference = nodes.reference('', '', internal=True)
                 if uri in self.images:
@@ -903,7 +939,7 @@ class StandaloneHTMLBuilder(Builder):
                     self.indexer.load(fb, self.indexer_format)
         except (OSError, ValueError):
             if keep:
-                logger.warning(__('search index couldn\'t be loaded, but not all '
+                logger.warning(__("search index couldn't be loaded, but not all "
                                   'documents will be built: the index will be '
                                   'incomplete.'))
         # delete all entries for files that will be rebuilt
@@ -930,7 +966,7 @@ class StandaloneHTMLBuilder(Builder):
     def get_outfilename(self, pagename: str) -> str:
         return path.join(self.outdir, os_path(pagename) + self.out_suffix)
 
-    def add_sidebars(self, pagename: str, ctx: Dict) -> None:
+    def add_sidebars(self, pagename: str, ctx: dict) -> None:
         def has_wildcard(pattern: str) -> bool:
             return any(char in pattern for char in '*?[')
 
@@ -985,8 +1021,8 @@ class StandaloneHTMLBuilder(Builder):
     def get_target_uri(self, docname: str, typ: str = None) -> str:
         return quote(docname) + self.link_suffix
 
-    def handle_page(self, pagename: str, addctx: Dict, templatename: str = 'page.html',
-                    outfilename: str = None, event_arg: Any = None) -> None:
+    def handle_page(self, pagename: str, addctx: dict, templatename: str = 'page.html',
+                    outfilename: str | None = None, event_arg: Any = None) -> None:
         ctx = self.globalcontext.copy()
         # current_page_name is backwards compatibility
         ctx['pagename'] = ctx['current_page_name'] = pagename
@@ -1002,7 +1038,9 @@ class StandaloneHTMLBuilder(Builder):
         else:
             ctx['pageurl'] = None
 
-        def pathto(otheruri: str, resource: bool = False, baseuri: str = default_baseuri) -> str:  # NOQA
+        def pathto(
+            otheruri: str, resource: bool = False, baseuri: str = default_baseuri,
+        ) -> str:
             if resource and '://' in otheruri:
                 # allow non-local resources given by scheme
                 return otheruri
@@ -1017,9 +1055,9 @@ class StandaloneHTMLBuilder(Builder):
         def hasdoc(name: str) -> bool:
             if name in self.env.all_docs:
                 return True
-            elif name == 'search' and self.search:
+            if name == 'search' and self.search:
                 return True
-            elif name == 'genindex' and self.get_builder_config('use_index', 'html'):
+            if name == 'genindex' and self.get_builder_config('use_index', 'html'):
                 return True
             return False
         ctx['hasdoc'] = hasdoc
@@ -1041,7 +1079,7 @@ class StandaloneHTMLBuilder(Builder):
         # sort JS/CSS before rendering HTML
         try:
             # Convert script_files to list to support non-list script_files (refs: #8889)
-            ctx['script_files'] = sorted(list(ctx['script_files']), key=lambda js: js.priority)
+            ctx['script_files'] = sorted(ctx['script_files'], key=lambda js: js.priority)
         except AttributeError:
             # Skip sorting if users modifies script_files directly (maybe via `html_context`).
             # refs: #8885
@@ -1050,7 +1088,7 @@ class StandaloneHTMLBuilder(Builder):
             pass
 
         try:
-            ctx['css_files'] = sorted(list(ctx['css_files']), key=lambda css: css.priority)
+            ctx['css_files'] = sorted(ctx['css_files'], key=lambda css: css.priority)
         except AttributeError:
             pass
 
@@ -1145,7 +1183,7 @@ class StandaloneHTMLBuilder(Builder):
             copyfile(self.env.doc2path(pagename), source_name)
 
     def update_page_context(self, pagename: str, templatename: str,
-                            ctx: Dict, event_arg: Any) -> None:
+                            ctx: dict, event_arg: Any) -> None:
         pass
 
     def handle_finish(self) -> None:
@@ -1174,7 +1212,7 @@ class StandaloneHTMLBuilder(Builder):
 
 def convert_html_css_files(app: Sphinx, config: Config) -> None:
     """This converts string styled html_css_files to tuple styled one."""
-    html_css_files: List[Tuple[str, Dict]] = []
+    html_css_files: list[tuple[str, dict]] = []
     for entry in config.html_css_files:
         if isinstance(entry, str):
             html_css_files.append((entry, {}))
@@ -1191,7 +1229,7 @@ def convert_html_css_files(app: Sphinx, config: Config) -> None:
 
 def convert_html_js_files(app: Sphinx, config: Config) -> None:
     """This converts string styled html_js_files to tuple styled one."""
-    html_js_files: List[Tuple[str, Dict]] = []
+    html_js_files: list[tuple[str, dict]] = []
     for entry in config.html_js_files:
         if isinstance(entry, str):
             html_js_files.append((entry, {}))
@@ -1207,7 +1245,7 @@ def convert_html_js_files(app: Sphinx, config: Config) -> None:
 
 
 def setup_css_tag_helper(app: Sphinx, pagename: str, templatename: str,
-                         context: Dict, doctree: Node) -> None:
+                         context: dict, doctree: Node) -> None:
     """Set up css_tag() template helper.
 
     .. note:: This set up function is added to keep compatibility with webhelper.
@@ -1219,7 +1257,7 @@ def setup_css_tag_helper(app: Sphinx, pagename: str, templatename: str,
         for key in sorted(css.attributes):
             value = css.attributes[key]
             if value is not None:
-                attrs.append('%s="%s"' % (key, html.escape(value, True)))
+                attrs.append(f'{key}="{html.escape(value, True)}"')
         attrs.append('href="%s"' % pathto(css.filename, resource=True))
         return '<link %s />' % ' '.join(attrs)
 
@@ -1227,7 +1265,7 @@ def setup_css_tag_helper(app: Sphinx, pagename: str, templatename: str,
 
 
 def setup_js_tag_helper(app: Sphinx, pagename: str, templatename: str,
-                        context: Dict, doctree: Node) -> None:
+                        context: dict, doctree: Node) -> None:
     """Set up js_tag() template helper.
 
     .. note:: This set up function is added to keep compatibility with webhelper.
@@ -1246,7 +1284,7 @@ def setup_js_tag_helper(app: Sphinx, pagename: str, templatename: str,
                     elif key == 'data_url_root':
                         attrs.append('data-url_root="%s"' % pathto('', resource=True))
                     else:
-                        attrs.append('%s="%s"' % (key, html.escape(value, True)))
+                        attrs.append(f'{key}="{html.escape(value, True)}"')
             if js.filename:
                 attrs.append('src="%s"' % pathto(js.filename, resource=True))
         else:
@@ -1254,31 +1292,27 @@ def setup_js_tag_helper(app: Sphinx, pagename: str, templatename: str,
             attrs.append('src="%s"' % pathto(js, resource=True))
 
         if attrs:
-            return '<script %s>%s</script>' % (' '.join(attrs), body)
+            return f'<script {" ".join(attrs)}>{body}</script>'
         else:
-            return '<script>%s</script>' % body
+            return f'<script>{body}</script>'
 
     context['js_tag'] = js_tag
 
 
 def setup_resource_paths(app: Sphinx, pagename: str, templatename: str,
-                         context: Dict, doctree: Node) -> None:
+                         context: dict, doctree: Node) -> None:
     """Set up relative resource paths."""
     pathto = context.get('pathto')
 
     # favicon_url
-    favicon = context.get('favicon')
-    if favicon and not isurl(favicon):
-        context['favicon_url'] = pathto('_static/' + favicon, resource=True)
-    else:
-        context['favicon_url'] = favicon
+    favicon_url = context.get('favicon_url')
+    if favicon_url and not isurl(favicon_url):
+        context['favicon_url'] = pathto('_static/' + favicon_url, resource=True)
 
     # logo_url
-    logo = context.get('logo')
-    if logo and not isurl(logo):
-        context['logo_url'] = pathto('_static/' + logo, resource=True)
-    else:
-        context['logo_url'] = logo
+    logo_url = context.get('logo_url')
+    if logo_url and not isurl(logo_url):
+        context['logo_url'] = pathto('_static/' + logo_url, resource=True)
 
 
 def validate_math_renderer(app: Sphinx) -> None:
@@ -1289,7 +1323,7 @@ def validate_math_renderer(app: Sphinx) -> None:
     if name is None:
         raise ConfigError(__('Many math_renderers are registered. '
                              'But no math_renderer is selected.'))
-    elif name not in app.registry.html_inline_math_renderers:
+    if name not in app.registry.html_inline_math_renderers:
         raise ConfigError(__('Unknown math_renderer %r is given.') % name)
 
 
@@ -1337,40 +1371,16 @@ def validate_html_favicon(app: Sphinx, config: Config) -> None:
         config.html_favicon = None  # type: ignore
 
 
-class _stable_repr_object():
-
-    def __repr__(self):
-        return '<object>'
-
-
-UNSET = _stable_repr_object()
-
-
-def migrate_html_add_permalinks(app: Sphinx, config: Config) -> None:
-    """Migrate html_add_permalinks to html_permalinks*."""
-    html_add_permalinks = config.html_add_permalinks
-    if html_add_permalinks is UNSET:
-        return
-
-    # RemovedInSphinx60Warning
-    logger.warning(__('html_add_permalinks has been deprecated since v3.5.0. '
-                      'Please use html_permalinks and html_permalinks_icon instead.'))
-    if not html_add_permalinks:
-        config.html_permalinks = False  # type: ignore[attr-defined]
-        return
-
-    config.html_permalinks_icon = html.escape(  # type: ignore[attr-defined]
-        html_add_permalinks
-    )
-
-# for compatibility
-import sphinxcontrib.serializinghtml  # NOQA
-
-import sphinx.builders.dirhtml  # NOQA
-import sphinx.builders.singlehtml  # NOQA
+def error_on_html_4(_app: Sphinx, config: Config) -> None:
+    """Error on HTML 4."""
+    if config.html4_writer:
+        raise ConfigError(_(
+            'HTML 4 is no longer supported by Sphinx. '
+            '("html4_writer=True" detected in configuration options)',
+        ))
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     # builders
     app.add_builder(StandaloneHTMLBuilder)
 
@@ -1382,7 +1392,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
                          lambda self: _('%s %s documentation') % (self.project, self.release),
                          'html', [str])
     app.add_config_value('html_short_title', lambda self: self.html_title, 'html')
-    app.add_config_value('html_style', None, 'html', [str])
+    app.add_config_value('html_style', None, 'html', [list, str])
     app.add_config_value('html_logo', None, 'html', [str])
     app.add_config_value('html_favicon', None, 'html', [str])
     app.add_config_value('html_css_files', [], 'html')
@@ -1393,7 +1403,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('html_sidebars', {}, 'html')
     app.add_config_value('html_additional_pages', {}, 'html')
     app.add_config_value('html_domain_indices', True, 'html', [list])
-    app.add_config_value('html_add_permalinks', UNSET, 'html')
     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')
@@ -1405,6 +1414,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('html_file_suffix', None, 'html', [str])
     app.add_config_value('html_link_suffix', None, 'html', [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')
@@ -1415,7 +1425,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('html_search_scorer', '', None)
     app.add_config_value('html_scaled_image_link', True, 'html')
     app.add_config_value('html_baseurl', '', 'html')
-    app.add_config_value('html_codeblock_linenos_style', 'inline', 'html',  # RemovedInSphinx60Warning  # NOQA
+    app.add_config_value('html_codeblock_linenos_style', 'inline', 'html',  # RemovedInSphinx70Warning  # noqa: E501
                          ENUM('table', 'inline'))
     app.add_config_value('html_math_renderer', None, 'env')
     app.add_config_value('html4_writer', False, 'html')
@@ -1427,11 +1437,11 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     # event handlers
     app.connect('config-inited', convert_html_css_files, priority=800)
     app.connect('config-inited', convert_html_js_files, priority=800)
-    app.connect('config-inited', migrate_html_add_permalinks, priority=800)
     app.connect('config-inited', validate_html_extra_path, priority=800)
     app.connect('config-inited', validate_html_static_path, priority=800)
     app.connect('config-inited', validate_html_logo, priority=800)
     app.connect('config-inited', validate_html_favicon, priority=800)
+    app.connect('config-inited', error_on_html_4, priority=800)
     app.connect('builder-inited', validate_math_renderer)
     app.connect('html-page-context', setup_css_tag_helper)
     app.connect('html-page-context', setup_js_tag_helper)
diff --git a/docs/lite/api/_custom/sphinx_writer_html5 b/docs/lite/api/_custom/sphinx_writer_html5
index 6ae120d5b61c7bcbdb5043c45787fb231d4d0722..bc944cfbc95c2c9bb565074f49e123aa9ea1fea3 100644
--- a/docs/lite/api/_custom/sphinx_writer_html5
+++ b/docs/lite/api/_custom/sphinx_writer_html5
@@ -1,20 +1,13 @@
-"""
-    sphinx.writers.html5
-    ~~~~~~~~~~~~~~~~~~~~
+"""Experimental docutils writers for HTML5 handling Sphinx's custom nodes."""
 
-    Experimental docutils writers for HTML5 handling Sphinx's custom nodes.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import os
 import posixpath
 import re
 import urllib.parse
 import sys
-import warnings
-from typing import TYPE_CHECKING, Iterable, Set, Tuple, cast
+from typing import TYPE_CHECKING, Iterable, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node, Text
@@ -22,7 +15,6 @@ from docutils.writers.html5_polyglot import HTMLTranslator as BaseTranslator
 
 from sphinx import addnodes
 from sphinx.builders import Builder
-from sphinx.deprecation import RemovedInSphinx50Warning, RemovedInSphinx60Warning
 from sphinx.locale import _, __, admonitionlabels
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxTranslator
@@ -43,12 +35,11 @@ def multiply_length(length: str, scale: int) -> str:
     matched = re.match(r'^(\d*\.?\d*)\s*(\S*)$', length)
     if not matched:
         return length
-    elif scale == 100:
+    if scale == 100:
         return length
-    else:
-        amount, unit = matched.groups()
-        result = float(amount) * scale / 100
-        return "%s%s" % (int(result), unit)
+    amount, unit = matched.groups()
+    result = float(amount) * scale / 100
+    return f"{int(result)}{unit}"
 
 
 class HTML5Translator(SphinxTranslator, BaseTranslator):
@@ -56,11 +47,11 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     Our custom HTML translator.
     """
 
-    builder: "StandaloneHTMLBuilder" = None
+    builder: StandaloneHTMLBuilder
     # Override docutils.writers.html5_polyglot:HTMLTranslator
     # otherwise, nodes like <inline classes="s">...</inline> will be
     # converted to <s>...</s> by `visit_inline`.
-    supported_inline_tags: Set[str] = set()
+    supported_inline_tags: set[str] = set()
 
     def __init__(self, document: nodes.document, builder: Builder) -> None:
         super().__init__(document, builder)
@@ -84,6 +75,13 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     def depart_start_of_file(self, node: Element) -> None:
         self.docnames.pop()
 
+    #############################################################
+    # Domain-specific object descriptions
+    #############################################################
+
+    # Top-level nodes for descriptions
+    ##################################
+
     def visit_desc(self, node: Element) -> None:
         self.body.append(self.starttag(node, 'dl'))
 
@@ -236,7 +234,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
                    'References must have "refuri" or "refid" attribute.'
             atts['href'] = '#' + node['refid']
         if not isinstance(node.parent, nodes.TextElement):
-            assert len(node) == 1 and isinstance(node[0], nodes.image)
+            assert len(node) == 1 and isinstance(node[0], nodes.image)  # NoQA: PT018
             atts['class'] += ' image-reference'
         if 'reftitle' in node:
             atts['title'] = node['reftitle']
@@ -265,20 +263,23 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
         if name:
             node.insert(0, nodes.title(name, admonitionlabels[name]))
 
+    def depart_admonition(self, node: Element | None = None) -> None:
+        self.body.append('</div>\n')
+
     def visit_seealso(self, node: Element) -> None:
         self.visit_admonition(node, 'seealso')
 
     def depart_seealso(self, node: Element) -> None:
         self.depart_admonition(node)
 
-    def get_secnumber(self, node: Element) -> Tuple[int, ...]:
+    def get_secnumber(self, node: Element) -> tuple[int, ...] | None:
         if node.get('secnumber'):
             return node['secnumber']
 
         if isinstance(node.parent, nodes.section):
             if self.builder.name == 'singlehtml':
                 docname = self.docnames[-1]
-                anchorname = "%s/#%s" % (docname, node.parent['ids'][0])
+                anchorname = "{}/#{}".format(docname, node.parent['ids'][0])
                 if anchorname not in self.builder.secnumbers:
                     anchorname = "%s/" % docname  # try first heading which has no anchor
             else:
@@ -300,7 +301,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     def add_fignumber(self, node: Element) -> None:
         def append_fignumber(figtype: str, figure_id: str) -> None:
             if self.builder.name == 'singlehtml':
-                key = "%s/%s" % (self.docnames[-1], figtype)
+                key = f"{self.docnames[-1]}/{figtype}"
             else:
                 key = figtype
 
@@ -395,12 +396,12 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
                 node.parent.hasattr('ids') and node.parent['ids']):
             # add permalink anchor
             if close_tag.startswith('</h'):
-                self.add_permalink_ref(node.parent, _('Permalink to this headline'))
+                self.add_permalink_ref(node.parent, _('Permalink to this heading'))
             elif close_tag.startswith('</a></h'):
                 self.body.append('</a><a class="headerlink" href="#%s" ' %
                                  node.parent['ids'][0] +
-                                 'title="%s">%s' % (
-                                     _('Permalink to this headline'),
+                                 'title="{}">{}'.format(
+                                     _('Permalink to this heading'),
                                      self.config.html_permalinks_icon))
             elif isinstance(node.parent, nodes.table):
                 self.body.append('</span>')
@@ -427,7 +428,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
 
         highlighted = self.highlighter.highlight_block(
             node.rawsource, lang, opts=opts, linenos=linenos,
-            location=node, **highlight_args
+            location=node, **highlight_args,
         )
         starttag = self.starttag(node, 'div', suffix='',
                                  CLASS='highlight-%s notranslate' % lang)
@@ -473,10 +474,25 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
         if 'kbd' in node['classes']:
             self.body.append(self.starttag(node, 'kbd', '',
                                            CLASS='docutils literal notranslate'))
-        else:
+            return
+        lang = node.get("language", None)
+        if 'code' not in node['classes'] or not lang:
             self.body.append(self.starttag(node, 'code', '',
                                            CLASS='docutils literal notranslate'))
             self.protect_literal_text += 1
+            return
+
+        opts = self.config.highlight_options.get(lang, {})
+        highlighted = self.highlighter.highlight_block(
+            node.astext(), lang, opts=opts, location=node, nowrap=True)
+        starttag = self.starttag(
+            node,
+            "code",
+            suffix="",
+            CLASS="docutils literal highlight highlight-%s" % lang,
+        )
+        self.body.append(starttag + highlighted.strip() + "</code>")
+        raise nodes.SkipNode
 
     def depart_literal(self, node: Element) -> None:
         if 'kbd' in node['classes']:
@@ -563,7 +579,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
         # rewrite the URI if the environment knows about it
         if olduri in self.builder.images:
             node['uri'] = posixpath.join(self.builder.imgpath,
-                                         self.builder.images[olduri])
+                                         urllib.parse.quote(self.builder.images[olduri]))
 
         if 'scale' in node:
             # Try to figure out image height and width.  Docutils does that too,
@@ -572,8 +588,10 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
             if not ('width' in node and 'height' in node):
                 size = get_image_size(os.path.join(self.builder.srcdir, olduri))
                 if size is None:
-                    logger.warning(__('Could not obtain image size. :scale: option is ignored.'),  # NOQA
-                                   location=node)
+                    logger.warning(
+                        __('Could not obtain image size. :scale: option is ignored.'),
+                        location=node,
+                    )
                 else:
                     if 'width' not in node:
                         node['width'] = str(size[0])
@@ -803,7 +821,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     def depart_math(self, node: Element, math_env: str = '') -> None:
         name = self.builder.math_renderer_name
         _, depart = self.builder.app.registry.html_inline_math_renderers[name]
-        if depart:
+        if depart:  # type: ignore[truthy-function]
             depart(self, node)
 
     def visit_math_block(self, node: Element, math_env: str = '') -> None:
@@ -814,38 +832,5 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
     def depart_math_block(self, node: Element, math_env: str = '') -> None:
         name = self.builder.math_renderer_name
         _, depart = self.builder.app.registry.html_block_math_renderers[name]
-        if depart:
+        if depart:  # type: ignore[truthy-function]
             depart(self, node)
-
-    @property
-    def permalink_text(self) -> str:
-        warnings.warn('HTMLTranslator.permalink_text is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-        return self.config.html_permalinks_icon
-
-    def generate_targets_for_table(self, node: Element) -> None:
-        """Generate hyperlink targets for tables.
-
-        Original visit_table() generates hyperlink targets inside table tags
-        (<table>) if multiple IDs are assigned to listings.
-        That is invalid DOM structure.  (This is a bug of docutils <= 0.13.1)
-
-        This exports hyperlink targets before tables to make valid DOM structure.
-        """
-        warnings.warn('generate_targets_for_table() is deprecated',
-                      RemovedInSphinx60Warning, stacklevel=2)
-        for id in node['ids'][1:]:
-            self.body.append('<span id="%s"></span>' % id)
-            node['ids'].remove(id)
-
-    @property
-    def _fieldlist_row_index(self):
-        warnings.warn('_fieldlist_row_index is deprecated',
-                      RemovedInSphinx60Warning, stacklevel=2)
-        return self._fieldlist_row_indices[-1]
-
-    @property
-    def _table_row_index(self):
-        warnings.warn('_table_row_index is deprecated',
-                      RemovedInSphinx60Warning, stacklevel=2)
-        return self._table_row_indices[-1]
diff --git a/docs/lite/api/_ext/customdocumenter.txt b/docs/lite/api/_ext/customdocumenter.txt
index 2d37ae41f6772a21da2a7dc5c7bff75128e68330..505ed7c57e6d7a30d106ca7a33111df6a8278ad3 100644
--- a/docs/lite/api/_ext/customdocumenter.txt
+++ b/docs/lite/api/_ext/customdocumenter.txt
@@ -8,7 +8,7 @@ class CustomDocumenter(Documenter):
     def document_members(self, all_members: bool = False) -> None:
         """Generate reST for member documentation.
 
-        If *all_members* is True, do all members, else those given by
+        If *all_members* is True, document all members, else those given by
         *self.options.members*.
         """
         # set current namespace for finding members
@@ -16,8 +16,9 @@ class CustomDocumenter(Documenter):
         if self.objpath:
             self.env.temp_data['autodoc:class'] = self.objpath[0]
 
-        want_all = all_members or self.options.inherited_members or \
-            self.options.members is ALL
+        want_all = (all_members or
+                    self.options.inherited_members or
+                    self.options.members is ALL)
         # find out which members are documentable
         members_check_module, members = self.get_object_members(want_all)
 
@@ -59,7 +60,7 @@ class CustomDocumenter(Documenter):
             ]
 
         # document non-skipped members
-        memberdocumenters = []  # type: List[Tuple[Documenter, bool]]
+        memberdocumenters: list[tuple[Documenter, bool]] = []
         for (mname, member, isattr) in self.filter_members(members, want_all):
             classes = [cls for cls in self.documenters.values()
                        if cls.can_document_member(member, mname, isattr, self)]
@@ -111,7 +112,7 @@ class CustomDocumenter(Documenter):
         if not self.parse_name():
             # need a module to import
             logger.warning(
-                __('don\'t know which module to import for autodocumenting '
+                __("don't know which module to import for autodocumenting "
                    '%r (try placing a "module" or "currentmodule" directive '
                    'in the document, or giving an explicit module name)') %
                 self.name, type='autodoc')
@@ -126,7 +127,8 @@ class CustomDocumenter(Documenter):
         # where the attribute documentation would actually be found in.
         # This is used for situations where you have a module that collects the
         # functions and classes of internal submodules.
-        self.real_modname = real_modname or self.get_real_modname()  # type: str
+        guess_modname = self.get_real_modname()
+        self.real_modname: str = real_modname or guess_modname
 
         # try to also get a source code analyzer for attribute docs
         try:
@@ -134,15 +136,28 @@ class CustomDocumenter(Documenter):
             # parse right now, to get PycodeErrors on parsing (results will
             # be cached anyway)
             self.analyzer.find_attr_docs()
-        except PycodeError as err:
-            logger.debug('[autodoc] module analyzer failed: %s', err)
+        except PycodeError as exc:
+            logger.debug('[autodoc] module analyzer failed: %s', exc)
             # no source file -- e.g. for builtin and C modules
             self.analyzer = None
             # at least add the module.__file__ as a dependency
             if hasattr(self.module, '__file__') and self.module.__file__:
-                self.directive.filename_set.add(self.module.__file__)
+                self.directive.record_dependencies.add(self.module.__file__)
         else:
-            self.directive.filename_set.add(self.analyzer.srcname)
+            self.directive.record_dependencies.add(self.analyzer.srcname)
+
+        if self.real_modname != guess_modname:
+            # Add module to dependency list if target object is defined in other module.
+            try:
+                analyzer = ModuleAnalyzer.for_module(guess_modname)
+                self.directive.record_dependencies.add(analyzer.srcname)
+            except PycodeError:
+                pass
+
+        docstrings: list[str] = sum(self.get_doc() or [], [])
+        if ismock(self.object) and not docstrings:
+            logger.warning(__('A mocked object is detected: %r'),
+                           self.name, type='autodoc')
 
         # check __module__ of object (for members not given explicitly)
         if check_module:
@@ -160,29 +175,41 @@ class ModuleDocumenter(CustomDocumenter):
     objtype = 'module'
     content_indent = ''
     titles_allowed = True
+    _extra_indent = '   '
 
-    option_spec = {
+    option_spec: OptionSpec = {
         'members': members_option, 'undoc-members': bool_option,
-        'noindex': bool_option, 'inherited-members': bool_option,
+        'noindex': bool_option, 'inherited-members': inherited_members_option,
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
-        'member-order': identity, 'exclude-members': members_set_option,
-        'private-members': bool_option, 'special-members': members_option,
-        'imported-members': bool_option, 'ignore-module-all': bool_option
-    }  # type: Dict[str, Callable]
+        'member-order': member_order_option, 'exclude-members': exclude_members_option,
+        'private-members': members_option, 'special-members': members_option,
+        'imported-members': bool_option, 'ignore-module-all': bool_option,
+        'no-value': bool_option,
+    }
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
         merge_members_option(self.options)
+        self.__all__: Sequence[str] | None = None
+
+    def add_content(self, more_content: StringList | None) -> None:
+        old_indent = self.indent
+        self.indent += self._extra_indent
+        super().add_content(None)
+        self.indent = old_indent
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         # don't document submodules automatically
         return False
 
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         if modname is not None:
             logger.warning(__('"::" in automodule name doesn\'t make sense'),
                            type='autodoc')
@@ -196,6 +223,20 @@ class ModuleDocumenter(CustomDocumenter):
                            type='autodoc')
         return ret
 
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+
+        try:
+            if not self.options.ignore_module_all:
+                self.__all__ = inspect.getall(self.object)
+        except ValueError as exc:
+            # invalid __all__ found.
+            logger.warning(__('__all__ should be a list of strings, not %r '
+                              '(in module %s) -- ignoring __all__') %
+                           (exc.args[0], self.fullname), type='autodoc')
+
+        return ret
+
     def add_directive_header(self, sig: str) -> None:
         Documenter.add_directive_header(self, sig)
 
@@ -209,37 +250,57 @@ class ModuleDocumenter(CustomDocumenter):
         if self.options.deprecated:
             self.add_line('   :deprecated:', sourcename)
 
-    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, object]]]:
+    def get_module_members(self) -> dict[str, ObjectMember]:
+        """Get members of target module."""
+        if self.analyzer:
+            attr_docs = self.analyzer.attr_docs
+        else:
+            attr_docs = {}
+
+        members: dict[str, ObjectMember] = {}
+        for name in dir(self.object):
+            try:
+                value = safe_getattr(self.object, name, None)
+                if ismock(value):
+                    value = undecorate(value)
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, value, docstring="\n".join(docstring))
+            except AttributeError:
+                continue
+
+        # annotation only member (ex. attr: int)
+        for name in inspect.getannotations(self.object):
+            if name not in members:
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, INSTANCEATTR,
+                                             docstring="\n".join(docstring))
+
+        return members
+
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        members = self.get_module_members()
         if want_all:
             if (self.options.ignore_module_all or not
                     hasattr(self.object, '__all__')):
                 # for implicit module members, check __module__ to avoid
                 # documenting imported objects
-                return True, get_module_members(self.object)
+                return True, list(members.values())
             else:
-                memberlist = self.object.__all__
-                # Sometimes __all__ is broken...
-                if not isinstance(memberlist, (list, tuple)) or not \
-                   all(isinstance(entry, str) for entry in memberlist):
-                    logger.warning(
-                        __('__all__ should be a list of strings, not %r '
-                           '(in module %s) -- ignoring __all__') %
-                        (memberlist, self.fullname),
-                        type='autodoc'
-                    )
-                    # fall back to all members
-                    return True, get_module_members(self.object)
+                for member in members.values():
+                    if member.__name__ not in self.__all__:
+                        member.skipped = True
+
+                # fall back to all members
+                return True,  list(members.values())
         else:
             memberlist = self.options.members or []
-        ret = []
-        for mname in memberlist:
-            try:
-                ret.append((mname, safe_getattr(self.object, mname)))
-            except AttributeError:
-                logger.warning(
-                    __('missing attribute mentioned in :members: or __all__: '
-                       'module %s, attribute %s') %
-                    (safe_getattr(self.object, '__name__', '???'), mname),
-                    type='autodoc'
-                )
-        return False, ret
+            ret = []
+            for name in memberlist:
+                if name in members:
+                    ret.append(members[name])
+                else:
+                    logger.warning(__('missing attribute mentioned in :members: option: '
+                                      'module %s, attribute %s') %
+                                   (safe_getattr(self.object, '__name__', '???'), name),
+                                   type='autodoc')
+            return False, ret
diff --git a/docs/lite/api/_ext/overwriteautosummary_generate.txt b/docs/lite/api/_ext/overwriteautosummary_generate.txt
index 4b0a1b1dd2b410ecab971b13da9993c90d65ef0d..23a4c166e123413b21d42f4eeab1accbc09b4896 100644
--- a/docs/lite/api/_ext/overwriteautosummary_generate.txt
+++ b/docs/lite/api/_ext/overwriteautosummary_generate.txt
@@ -1,22 +1,19 @@
-"""
-    sphinx.ext.autosummary.generate
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Usable as a library or script to generate automatic RST source files for
-    items referred to in autosummary:: directives.
+"""Generates reST source files for autosummary.
 
-    Each generated RST file contains a single auto*:: directive which
-    extracts the docstring of the referred item.
+Usable as a library or script to generate automatic RST source files for
+items referred to in autosummary:: directives.
 
-    Example Makefile rule::
+Each generated RST file contains a single auto*:: directive which
+extracts the docstring of the referred item.
 
-       generate:
-               sphinx-autogen -o source/generated source/*.rst
+Example Makefile rule::
 
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+   generate:
+           sphinx-autogen -o source/generated source/*.rst
 """
 
+from __future__ import annotations
+
 import argparse
 import importlib
 import inspect
@@ -26,10 +23,8 @@ import pkgutil
 import pydoc
 import re
 import sys
-import warnings
-from gettext import NullTranslations
 from os import path
-from typing import Any, Dict, List, NamedTuple, Sequence, Set, Tuple, Type, Union
+from typing import TYPE_CHECKING, Any, NamedTuple, Sequence
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -39,11 +34,14 @@ from sphinx import __display_version__, package_dir
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import Config
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.ext.autodoc import Documenter
 from sphinx.ext.autodoc.importer import import_module
-from sphinx.ext.autosummary import (ImportExceptionGroup, get_documenter, import_by_name,
-                                    import_ivar_by_name)
+from sphinx.ext.autosummary import (
+    ImportExceptionGroup,
+    get_documenter,
+    import_by_name,
+    import_ivar_by_name,
+)
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.registry import SphinxComponentRegistry
@@ -52,6 +50,9 @@ from sphinx.util.inspect import getall, safe_getattr
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxTemplateLoader
 
+if TYPE_CHECKING:
+    from gettext import NullTranslations
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,7 +62,7 @@ class DummyApplication:
     def __init__(self, translator: NullTranslations) -> None:
         self.config = Config()
         self.registry = SphinxComponentRegistry()
-        self.messagelog: List[str] = []
+        self.messagelog: list[str] = []
         self.srcdir = "/"
         self.translator = translator
         self.verbosity = 0
@@ -91,32 +92,26 @@ class AutosummaryEntry(NamedTuple):
 
 
 def setup_documenters(app: Any) -> None:
-    from sphinx.ext.autodoc import (AttributeDocumenter, ClassDocumenter, DataDocumenter,
-                                    DecoratorDocumenter, ExceptionDocumenter,
-                                    FunctionDocumenter, MethodDocumenter, ModuleDocumenter,
-                                    NewTypeAttributeDocumenter, NewTypeDataDocumenter,
-                                    PropertyDocumenter)
-    documenters: List[Type[Documenter]] = [
+    from sphinx.ext.autodoc import (
+        AttributeDocumenter,
+        ClassDocumenter,
+        DataDocumenter,
+        DecoratorDocumenter,
+        ExceptionDocumenter,
+        FunctionDocumenter,
+        MethodDocumenter,
+        ModuleDocumenter,
+        PropertyDocumenter,
+    )
+    documenters: list[type[Documenter]] = [
         ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter,
-        FunctionDocumenter, MethodDocumenter, NewTypeAttributeDocumenter,
-        NewTypeDataDocumenter, AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
+        FunctionDocumenter, MethodDocumenter,
+        AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
     ]
     for documenter in documenters:
         app.registry.add_documenter(documenter.objtype, documenter)
 
 
-def _simple_info(msg: str) -> None:
-    warnings.warn('_simple_info() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print(msg)
-
-
-def _simple_warn(msg: str) -> None:
-    warnings.warn('_simple_warn() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print('WARNING: ' + msg, file=sys.stderr)
-
-
 def _underline(title: str, line: str = '=') -> str:
     if '\n' in title:
         raise ValueError('Can only underline single lines')
@@ -126,14 +121,9 @@ def _underline(title: str, line: str = '=') -> str:
 class AutosummaryRenderer:
     """A helper class for rendering."""
 
-    def __init__(self, app: Union[Builder, Sphinx], template_dir: str = None) -> None:
+    def __init__(self, app: Sphinx) -> None:
         if isinstance(app, Builder):
-            warnings.warn('The first argument for AutosummaryRenderer has been '
-                          'changed to Sphinx object',
-                          RemovedInSphinx50Warning, stacklevel=2)
-        if template_dir:
-            warnings.warn('template_dir argument for AutosummaryRenderer is deprecated.',
-                          RemovedInSphinx50Warning, stacklevel=2)
+            raise ValueError('Expected a Sphinx application object!')
 
         system_templates_path = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')]
         loader = SphinxTemplateLoader(app.srcdir, app.config.templates_path,
@@ -144,26 +134,11 @@ class AutosummaryRenderer:
         self.env.filters['e'] = rst.escape
         self.env.filters['underline'] = _underline
 
-        if isinstance(app, (Sphinx, DummyApplication)):
-            if app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.translator)
-        elif isinstance(app, Builder):
-            if app.app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.app.translator)
-
-    def exists(self, template_name: str) -> bool:
-        """Check if template file exists."""
-        warnings.warn('AutosummaryRenderer.exists() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-        try:
-            self.env.get_template(template_name)
-            return True
-        except TemplateNotFound:
-            return False
+        if app.translator:
+            self.env.add_extension("jinja2.ext.i18n")
+            self.env.install_gettext_translations(app.translator)
 
-    def render(self, template_name: str, context: Dict) -> str:
+    def render(self, template_name: str, context: dict) -> str:
         """Render a template file."""
         try:
             template = self.env.get_template(template_name)
@@ -199,8 +174,14 @@ class ModuleScanner:
                            name, exc, type='autosummary')
             return False
 
-    def scan(self, imported_members: bool) -> List[str]:
+    def scan(self, imported_members: bool) -> list[str]:
         members = []
+        try:
+            analyzer = ModuleAnalyzer.for_module(self.object.__name__)
+            attr_docs = analyzer.find_attr_docs()
+        except PycodeError:
+            attr_docs = {}
+
         for name in members_of(self.object, self.app.config):
             try:
                 value = safe_getattr(self.object, name)
@@ -212,7 +193,9 @@ class ModuleScanner:
                 continue
 
             try:
-                if inspect.ismodule(value):
+                if ('', name) in attr_docs:
+                    imported = False
+                elif inspect.ismodule(value):  # NoQA: SIM114
                     imported = True
                 elif safe_getattr(value, '__module__') != self.object.__name__:
                     imported = True
@@ -222,14 +205,14 @@ class ModuleScanner:
                 imported = False
 
             respect_module_all = not self.app.config.autosummary_ignore_module_all
-            if imported_members:
+            if (
                 # list all members up
-                members.append(name)
-            elif imported is False:
+                imported_members
                 # list not-imported members
-                members.append(name)
-            elif '__all__' in dir(self.object) and respect_module_all:
+                or imported is False
                 # list members that have __all__ set
+                or (respect_module_all and '__all__' in dir(self.object))
+            ):
                 members.append(name)
 
         return members
@@ -249,8 +232,9 @@ def members_of(obj: Any, conf: Config) -> Sequence[str]:
 def generate_autosummary_content(name: str, obj: Any, parent: Any,
                                  template: AutosummaryRenderer, template_name: str,
                                  imported_members: bool, app: Any,
-                                 recursive: bool, context: Dict,
-                                 modname: str = None, qualname: str = None) -> str:
+                                 recursive: bool, context: dict,
+                                 modname: str | None = None,
+                                 qualname: str | None = None) -> str:
     doc = get_documenter(app, obj, parent)
 
     def skip_member(obj: Any, name: str, objtype: str) -> bool:
@@ -263,11 +247,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                            name, exc, type='autosummary')
             return False
 
-    def get_class_members(obj: Any) -> Dict[str, Any]:
+    def get_class_members(obj: Any) -> dict[str, Any]:
         members = sphinx.ext.autodoc.get_class_members(obj, [qualname], safe_getattr)
         return {name: member.object for name, member in members.items()}
 
-    def get_module_members(obj: Any) -> Dict[str, Any]:
+    def get_module_members(obj: Any) -> dict[str, Any]:
         members = {}
         for name in members_of(obj, app.config):
             try:
@@ -276,17 +260,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 continue
         return members
 
-    def get_all_members(obj: Any) -> Dict[str, Any]:
+    def get_all_members(obj: Any) -> dict[str, Any]:
         if doc.objtype == "module":
             return get_module_members(obj)
         elif doc.objtype == "class":
             return get_class_members(obj)
         return {}
 
-    def get_members(obj: Any, types: Set[str], include_public: List[str] = [],
-                    imported: bool = True) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
-        public: List[str] = []
+    def get_members(obj: Any, types: set[str], include_public: list[str] = [],
+                    imported: bool = True) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
 
         all_members = get_all_members(obj)
         for name, value in all_members.items():
@@ -308,7 +292,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                             public.append(name)
         return public, items
 
-    def get_module_attrs(members: Any) -> Tuple[List[str], List[str]]:
+    def get_module_attrs(members: Any) -> tuple[list[str], list[str]]:
         """Find module attributes with docstrings."""
         attrs, public = [], []
         try:
@@ -323,9 +307,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             pass    # give up if ModuleAnalyzer fails to parse code
         return public, attrs
 
-    def get_modules(obj: Any) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
+    def get_modules(
+            obj: Any,
+            skip: Sequence[str],
+            public_members: Sequence[str] | None = None) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
         for _, modname, _ispkg in pkgutil.iter_modules(obj.__path__):
+
+            if modname in skip:
+                # module was overwritten in __init__.py, so not accessible
+                continue
             fullname = name + '.' + modname
             try:
                 module = import_module(fullname)
@@ -335,15 +327,24 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 pass
 
             items.append(fullname)
-        public = [x for x in items if not x.split('.')[-1].startswith('_')]
+            if public_members is not None:
+                if modname in public_members:
+                    public.append(fullname)
+            else:
+                if not modname.startswith('_'):
+                    public.append(fullname)
         return public, items
 
-    ns: Dict[str, Any] = {}
+    ns: dict[str, Any] = {}
     ns.update(context)
 
     if doc.objtype == 'module':
         scanner = ModuleScanner(app, obj)
         ns['members'] = scanner.scan(imported_members)
+
+        respect_module_all = not app.config.autosummary_ignore_module_all
+        imported_members = imported_members or ('__all__' in dir(obj) and respect_module_all)
+
         ns['functions'], ns['all_functions'] = \
             get_members(obj, {'function'}, imported=imported_members)
         ns['classes'], ns['all_classes'] = \
@@ -354,7 +355,36 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             get_module_attrs(ns['members'])
         ispackage = hasattr(obj, '__path__')
         if ispackage and recursive:
-            ns['modules'], ns['all_modules'] = get_modules(obj)
+            # Use members that are not modules as skip list, because it would then mean
+            # that module was overwritten in the package namespace
+            skip = (
+                ns["all_functions"]
+                + ns["all_classes"]
+                + ns["all_exceptions"]
+                + ns["all_attributes"]
+            )
+
+            # If respect_module_all and module has a __all__ attribute, first get
+            # modules that were explicitly imported. Next, find the rest with the
+            # get_modules method, but only put in "public" modules that are in the
+            # __all__ list
+            #
+            # Otherwise, use get_modules method normally
+            if respect_module_all and '__all__' in dir(obj):
+                imported_modules, all_imported_modules = \
+                    get_members(obj, {'module'}, imported=True)
+                skip += all_imported_modules
+                imported_modules = [name + '.' + modname for modname in imported_modules]
+                all_imported_modules = \
+                    [name + '.' + modname for modname in all_imported_modules]
+                public_members = getall(obj)
+            else:
+                imported_modules, all_imported_modules = [], []
+                public_members = None
+
+            modules, all_modules = get_modules(obj, skip=skip, public_members=public_members)
+            ns['modules'] = imported_modules + modules
+            ns["all_modules"] = all_imported_modules + all_modules
     elif doc.objtype == 'class':
         ns['members'] = dir(obj)
         ns['inherited_members'] = \
@@ -389,21 +419,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         return template.render(doc.objtype, ns)
 
 
-def generate_autosummary_docs(sources: List[str], output_dir: str = None,
-                              suffix: str = '.rst', base_path: str = None,
-                              builder: Builder = None, template_dir: str = None,
+def generate_autosummary_docs(sources: list[str], output_dir: str | None = None,
+                              suffix: str = '.rst', base_path: str | None = None,
                               imported_members: bool = False, app: Any = None,
                               overwrite: bool = True, encoding: str = 'utf-8') -> None:
-
-    if builder:
-        warnings.warn('builder argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    if template_dir:
-        warnings.warn('template_dir argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    showed_sources = list(sorted(sources))
+    showed_sources = sorted(sources)
     if len(showed_sources) > 20:
         showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:]
     logger.info(__('[autosummary] generating autosummary for: %s') %
@@ -439,7 +459,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
         ensuredir(path)
 
         try:
-            name, obj, parent, modname = import_by_name(entry.name, grouped_exception=True)
+            name, obj, parent, modname = import_by_name(entry.name)
             qualname = name.replace(modname + ".", "")
         except ImportExceptionGroup as exc:
             try:
@@ -448,16 +468,16 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
                 qualname = name.replace(modname + ".", "")
             except ImportError as exc2:
                 if exc2.__cause__:
-                    exceptions: List[BaseException] = exc.exceptions + [exc2.__cause__]
+                    exceptions: list[BaseException] = exc.exceptions + [exc2.__cause__]
                 else:
                     exceptions = exc.exceptions + [exc2]
 
-                errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exceptions))
+                errors = list({f"* {type(e).__name__}: {e}" for e in exceptions})
                 logger.warning(__('[autosummary] failed to import %s.\nPossible hints:\n%s'),
                                entry.name, '\n'.join(errors))
                 continue
 
-        context: Dict[str, Any] = {}
+        context: dict[str, Any] = {}
         if app:
             context.update(app.config.autosummary_context)
 
@@ -484,7 +504,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
 
             if content == old_content:
                 continue
-            elif overwrite:  # content has changed
+            if overwrite:  # content has changed
                 with open(filename, 'w', encoding=encoding) as f:
                     f.write(content)
                 new_files.append(filename)
@@ -497,19 +517,18 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     if new_files:
         generate_autosummary_docs(new_files, output_dir=output_dir,
                                   suffix=suffix, base_path=base_path,
-                                  builder=builder, template_dir=template_dir,
                                   imported_members=imported_members, app=app,
                                   overwrite=overwrite)
 
 
 # -- Finding documented entries in files ---------------------------------------
 
-def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
+def find_autosummary_in_files(filenames: list[str]) -> list[AutosummaryEntry]:
     """Find out what items are documented in source/*.rst.
 
     See `find_autosummary_in_lines`.
     """
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
     for filename in filenames:
         with open(filename, encoding='utf-8', errors='ignore') as f:
             lines = f.read().splitlines()
@@ -517,33 +536,31 @@ def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
     return documented
 
 
-def find_autosummary_in_docstring(name: str, module: str = None, filename: str = None
-                                  ) -> List[AutosummaryEntry]:
+def find_autosummary_in_docstring(
+    name: str, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items are documented in the given object's docstring.
 
     See `find_autosummary_in_lines`.
     """
-    if module:
-        warnings.warn('module argument for find_autosummary_in_docstring() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
     try:
-        real_name, obj, parent, modname = import_by_name(name, grouped_exception=True)
+        real_name, obj, parent, modname = import_by_name(name)
         lines = pydoc.getdoc(obj).splitlines()
         return find_autosummary_in_lines(lines, module=name, filename=filename)
     except AttributeError:
         pass
     except ImportExceptionGroup as exc:
-        errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exc.exceptions))
-        print('Failed to import %s.\nPossible hints:\n%s' % (name, '\n'.join(errors)))
+        errors = '\n'.join({f"* {type(e).__name__}: {e}" for e in exc.exceptions})
+        print(f'Failed to import {name}.\nPossible hints:\n{errors}')
     except SystemExit:
         print("Failed to import '%s'; the module executes module level "
               "statement and it might call sys.exit()." % name)
     return []
 
 
-def find_autosummary_in_lines(lines: List[str], module: str = None, filename: str = None
-                              ) -> List[AutosummaryEntry]:
+def find_autosummary_in_lines(
+    lines: list[str], module: str | None = None, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items appear in autosummary:: directives in the
     given lines.
 
@@ -564,10 +581,10 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
     toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$')
     template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$')
 
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
 
     recursive = False
-    toctree: str = None
+    toctree: str | None = None
     template = None
     current_module = module
     in_autosummary = False
@@ -603,7 +620,7 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
                     name = name[1:]
                 if current_module and \
                    not name.startswith(current_module + '.'):
-                    name = "%s.%s" % (current_module, name)
+                    name = f"{current_module}.{name}"
                 documented.append(AutosummaryEntry(name, toctree, template, recursive))
                 continue
 
@@ -683,12 +700,11 @@ The format of the autosummary directive is documented in the
     return parser
 
 
-def main(argv: List[str] = sys.argv[1:]) -> None:
-    sphinx.locale.setlocale(locale.LC_ALL, '')
-    sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
-    translator, _ = sphinx.locale.init([], None)
+def main(argv: list[str] = sys.argv[1:]) -> None:
+    locale.setlocale(locale.LC_ALL, '')
+    sphinx.locale.init_console()
 
-    app = DummyApplication(translator)
+    app = DummyApplication(sphinx.locale.get_translator())
     logging.setup(app, sys.stdout, sys.stderr)  # type: ignore
     setup_documenters(app)
     args = get_parser().parse_args(argv)
diff --git a/docs/lite/api/_ext/overwriteobjectiondirective.txt b/docs/lite/api/_ext/overwriteobjectiondirective.txt
index f77828412afd6da7f8c14b04fa044e23eb6855a9..669be7eb3030776b9c632c09002d9016779e9c07 100644
--- a/docs/lite/api/_ext/overwriteobjectiondirective.txt
+++ b/docs/lite/api/_ext/overwriteobjectiondirective.txt
@@ -1,17 +1,11 @@
-"""
-    sphinx.directives
-    ~~~~~~~~~~~~~~~~~
+"""Handlers for additional ReST directives."""
 
-    Handlers for additional ReST directives.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import re
 import inspect
 import importlib
-from typing import TYPE_CHECKING, Any, Dict, Generic, List, Tuple, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, List, TypeVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -19,10 +13,10 @@ from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
 from sphinx.addnodes import desc_signature
-from sphinx.deprecation import RemovedInSphinx50Warning, deprecated_alias
 from sphinx.util import docutils, logging
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
@@ -33,10 +27,11 @@ if TYPE_CHECKING:
 nl_escape_re = re.compile(r'\\\n')
 strip_backslash_re = re.compile(r'\\(.)')
 
-T = TypeVar('T')
+ObjDescT = TypeVar('ObjDescT')
+
 logger = logging.getLogger(__name__)
 
-def optional_int(argument: str) -> int:
+def optional_int(argument: str) -> int | None:
     """
     Check for an integer argument or None value; raise ``ValueError`` if not.
     """
@@ -84,23 +79,23 @@ def get_example(name: str):
 def get_platforms(name: str):
     try:
         api_doc = inspect.getdoc(get_api(name))
-        example_str = re.findall(r'Supported Platforms:\n\s+(.*?)\n\n', api_doc)
-        if not example_str:
-            example_str_leak = re.findall(r'Supported Platforms:\n\s+(.*)', api_doc)
-            if example_str_leak:
-                example_str = example_str_leak[0].strip()
-                example_list = example_str.split('\n')
-                example_list = ['    ' + example_list[0]]
-                return ["", "支持平台："] + example_list + [""]
+        platform_str = re.findall(r'Supported Platforms:\n\s+(.*?)\n\n', api_doc)
+        if not platform_str:
+            platform_str_leak = re.findall(r'Supported Platforms:\n\s+(.*)', api_doc)
+            if platform_str_leak:
+                platform_str = platform_str_leak[0].strip()
+                platform_list = platform_str.split('\n')
+                platform_list = ['    ' + platform_list[0]]
+                return ["", "支持平台："] + platform_list + [""]
             return []
-        example_str = example_str[0].strip()
-        example_list = example_str.split('\n')
-        example_list = ['    ' + example_list[0]]
-        return ["", "支持平台："] + example_list + [""]
+        platform_str = platform_str[0].strip()
+        platform_list = platform_str.split('\n')
+        platform_list = ['    ' + platform_list[0]]
+        return ["", "支持平台："] + platform_list + [""]
     except:
         return []
 
-class ObjectDescription(SphinxDirective, Generic[T]):
+class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     """
     Directive to describe a class, function or similar object.  Not used
     directly, but subclassed (in domain-specific directives) to add custom
@@ -113,18 +108,20 @@ class ObjectDescription(SphinxDirective, Generic[T]):
     final_argument_whitespace = True
     option_spec: OptionSpec = {
         'noindex': directives.flag,
-    }  # type: Dict[str, DirectiveOption]
+        'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
+    }
 
     # types of doc fields that this directive handles, see sphinx.util.docfields
-    doc_field_types: List[Field] = []
-    domain: str = None
-    objtype: str = None
-    indexnode: addnodes.index = None
+    doc_field_types: list[Field] = []
+    domain: str | None = None
+    objtype: str  # set when `run` method is called
+    indexnode: addnodes.index
 
     # Warning: this might be removed in future version. Don't touch this from extensions.
-    _doc_field_type_map = {}  # type: Dict[str, Tuple[Field, bool]]
+    _doc_field_type_map: dict[str, tuple[Field, bool]] = {}
 
-    def get_field_type_map(self) -> Dict[str, Tuple[Field, bool]]:
+    def get_field_type_map(self) -> dict[str, tuple[Field, bool]]:
         if self._doc_field_type_map == {}:
             self._doc_field_type_map = {}
             for field in self.doc_field_types:
@@ -138,12 +135,10 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         return self._doc_field_type_map
 
-    def get_signatures(self) -> List[str]:
+    def get_signatures(self) -> list[str]:
         """
         Retrieve the signatures to document from the directive arguments.  By
         default, signatures are given as arguments, one per line.
-
-        Backslash-escaping of newlines is supported.
         """
         lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
         if self.config.strip_signature_backslash:
@@ -152,7 +147,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         else:
             return [line.strip() for line in lines]
 
-    def handle_signature(self, sig: str, signode: desc_signature) -> Any:
+    def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
         """
         Parse the signature *sig* into individual nodes and append them to
         *signode*. If ValueError is raised, parsing is aborted and the whole
@@ -164,7 +159,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         """
         raise ValueError
 
-    def add_target_and_index(self, name: Any, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -195,6 +190,44 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         """
         pass
 
+    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
+        """
+        Returns a tuple of strings, one entry for each part of the object's
+        hierarchy (e.g. ``('module', 'submodule', 'Class', 'method')``). The
+        returned tuple is used to properly nest children within parents in the
+        table of contents, and can also be used within the
+        :py:meth:`_toc_entry_name` method.
+
+        This method must not be used outwith table of contents generation.
+        """
+        return ()
+
+    def _toc_entry_name(self, sig_node: desc_signature) -> str:
+        """
+        Returns the text of the table of contents entry for the object.
+
+        This function is called once, in :py:meth:`run`, to set the name for the
+        table of contents entry (a special attribute ``_toc_name`` is set on the
+        object node, later used in
+        ``environment.collectors.toctree.TocTreeCollector.process_doc().build_toc()``
+        when the table of contents entries are collected).
+
+        To support table of contents entries for their objects, domains must
+        override this method, also respecting the configuration setting
+        ``toc_object_entries_show_parents``. Domains must also override
+        :py:meth:`_object_hierarchy_parts`, with one (string) entry for each part of the
+        object's hierarchy. The result of this method is set on the signature
+        node, and can be accessed as ``sig_node['_toc_parts']`` for use within
+        this method. The resulting tuple is also used to properly nest children
+        within parents in the table of contents.
+
+        An example implementations of this method is within the python domain
+        (:meth:`!PyObject._toc_entry_name`). The python domain sets the
+        ``_toc_parts`` attribute within the :py:meth:`handle_signature()`
+        method.
+        """
+        return ''
+
     def check_class_end(self, content):
         for i in content:
             if not i.startswith('.. include::') and i != "\n" and i != "":
@@ -207,7 +240,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
             ls.append((rst_file, start_num+i))
         return ls
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         """
         Main directive entry function, called by docutils upon encountering the
         directive.
@@ -233,15 +266,28 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         node = addnodes.desc()
         node.document = self.state.document
+        source, line = self.get_source_info()
+        # If any options were specified to the directive,
+        # self.state.document.current_line will at this point be set to
+        # None.  To ensure nodes created as part of the signature have a line
+        # number set, set the document's line number correctly.
+        #
+        # Note that we need to subtract one from the line number since
+        # note_source uses 0-based line numbers.
+        if line is not None:
+            line -= 1
+        self.state.document.note_source(source, line)
         node['domain'] = self.domain
         # 'desctype' is a backwards compatible attribute
         node['objtype'] = node['desctype'] = self.objtype
         node['noindex'] = noindex = ('noindex' in self.options)
+        node['noindexentry'] = ('noindexentry' in self.options)
+        node['nocontentsentry'] = ('nocontentsentry' in self.options)
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
 
-        self.names: List[T] = []
+        self.names: list[ObjDescT] = []
         signatures = self.get_signatures()
         for sig in signatures:
             # add a signature node for each signature in the current unit
@@ -259,6 +305,15 @@ class ObjectDescription(SphinxDirective, Generic[T]):
                 signode.clear()
                 signode += addnodes.desc_name(sig, sig)
                 continue  # we don't want an index entry here
+            finally:
+                # Private attributes for ToC generation. Will be modified or removed
+                # without notice.
+                if self.env.app.config.toc_object_entries:
+                    signode['_toc_parts'] = self._object_hierarchy_parts(signode)
+                    signode['_toc_name'] = self._toc_entry_name(signode)
+                else:
+                    signode['_toc_parts'] = ()
+                    signode['_toc_name'] = ''
             if name not in self.names:
                 self.names.append(name)
                 if not noindex:
@@ -268,6 +323,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         contentnode = addnodes.desc_content()
         node.append(contentnode)
+
         if self.names:
             # needed for association of version{added,changed} directives
             self.env.temp_data['object'] = self.names[0]
@@ -300,7 +356,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
             self.content.items.extend(self.extend_items(self.content.items[0][0], self.content.items[-1][1], len(extra)))
         except Exception as e:
             logger.warning(f'{e}')
-        self.state.nested_parse(self.content, self.content_offset, contentnode)
+        nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
         self.transform_content(contentnode)
         self.env.app.emit('object-description-transform',
                           self.domain, self.objtype, contentnode)
@@ -318,14 +374,14 @@ class DefaultRole(SphinxDirective):
     optional_arguments = 1
     final_argument_whitespace = False
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         if not self.arguments:
             docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
         role, messages = roles.role(role_name, self.state_machine.language,
                                     self.lineno, self.state.reporter)
-        if role:
+        if role:  # type: ignore[truthy-function]
             docutils.register_role('', role)
             self.env.temp_data['default_role'] = role_name
         else:
@@ -347,9 +403,9 @@ class DefaultDomain(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()
         # if domain_name not in env.domains:
         #     # try searching by label
@@ -360,7 +416,8 @@ class DefaultDomain(SphinxDirective):
         self.env.temp_data['default_domain'] = self.env.domains.get(domain_name)
         return []
 
-def setup(app: "Sphinx") -> Dict[str, Any]:
+
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value("strip_signature_backslash", False, 'env')
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)
diff --git a/docs/lite/api/_ext/overwriteviewcode.txt b/docs/lite/api/_ext/overwriteviewcode.txt
index 172780ec56b3ed90e7b0add617257a618cf38ee0..a2fdcfb787bb99e6d96742574675f79151a4848d 100644
--- a/docs/lite/api/_ext/overwriteviewcode.txt
+++ b/docs/lite/api/_ext/overwriteviewcode.txt
@@ -1,18 +1,12 @@
-"""
-    sphinx.ext.viewcode
-    ~~~~~~~~~~~~~~~~~~~
+"""Add links to module code in Python object descriptions."""
 
-    Add links to module code in Python object descriptions.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import posixpath
 import traceback
 import warnings
 from os import path
-from typing import Any, Dict, Generator, Iterable, Optional, Set, Tuple, cast
+from typing import Any, Generator, Iterable, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
@@ -22,12 +16,12 @@ from sphinx import addnodes
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import get_full_modname, logging, status_iterator
+from sphinx.util import get_full_modname, logging
+from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
 
 
@@ -46,13 +40,13 @@ class viewcode_anchor(Element):
     """
 
 
-def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str]:
+def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> str | None:
     try:
         return get_full_modname(modname, attribute)
     except AttributeError:
         # sphinx.ext.viewcode can't follow class instance attribute
         # then AttributeError logging output only verbose mode.
-        logger.verbose('Didn\'t find %s in %s', attribute, modname)
+        logger.verbose("Didn't find %s in %s", attribute, modname)
         return None
     except Exception as e:
         # sphinx.ext.viewcode follow python domain directives.
@@ -67,12 +61,11 @@ def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str
 def is_supported_builder(builder: Builder) -> bool:
     if builder.format != 'html':
         return False
-    elif builder.name == 'singlehtml':
+    if builder.name == 'singlehtml':
         return False
-    elif builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
+    if builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
         return False
-    else:
-        return True
+    return True
 
 
 def doctree_read(app: Sphinx, doctree: Node) -> None:
@@ -112,7 +105,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
     for objnode in list(doctree.findall(addnodes.desc)):
         if objnode.get('domain') != 'py':
             continue
-        names: Set[str] = set()
+        names: set[str] = set()
         for signode in objnode:
             if not isinstance(signode, addnodes.desc_signature):
                 continue
@@ -211,19 +204,7 @@ class ViewcodeAnchorTransform(SphinxPostTransform):
             node.parent.remove(node)
 
 
-def missing_reference(app: Sphinx, env: BuildEnvironment, node: Element, contnode: Node
-                      ) -> Optional[Node]:
-    # resolve our "viewcode" reference nodes -- they need special treatment
-    if node['reftype'] == 'viewcode':
-        warnings.warn('viewcode extension is no longer use pending_xref node. '
-                      'Please update your extension.', RemovedInSphinx50Warning)
-        return make_refnode(app.builder, node['refdoc'], node['reftarget'],
-                            node['refid'], contnode)
-
-    return None
-
-
-def get_module_filename(app: Sphinx, modname: str) -> Optional[str]:
+def get_module_filename(app: Sphinx, modname: str) -> str | None:
     """Get module filename for *modname*."""
     source_info = app.emit_firstresult('viewcode-find-source', modname)
     if source_info:
@@ -251,13 +232,13 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
         if path.getmtime(module_filename) <= path.getmtime(page_filename):
             # generation is not needed if the HTML page is newer than module file.
             return False
-    except IOError:
+    except OSError:
         pass
 
     return True
 
 
-def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], None, None]:
+def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], None, None]:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
         return
@@ -282,7 +263,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
         # construct a page name for the highlighted source
         pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))
         # highlight the source using the builder's highlighter
-        if env.config.highlight_language in ('python3', 'default', 'none'):
+        if env.config.highlight_language in {'default', 'none'}:
             lexer = env.config.highlight_language
         else:
             lexer = 'python'
@@ -343,10 +324,9 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
                 stack.pop()
                 html.append('</ul>')
             stack.append(modname + '.')
-        html.append('<li><a href="%s">%s</a></li>\n' % (
-            urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
-                  posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))),
-            modname))
+        relative_uri = urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
+                             posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/')))
+        html.append(f'<li><a href="{relative_uri}">{modname}</a></li>\n')
     html.append('</ul>' * (len(stack) - 1))
     context = {
         'title': _('Overview: module code'),
@@ -357,7 +337,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
     yield (posixpath.join(OUTPUT_DIRNAME, 'index'), context, 'page.html')
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('viewcode_import', None, False)
     app.add_config_value('viewcode_enable_epub', False, False)
     app.add_config_value('viewcode_follow_imported_members', True, False)
@@ -365,7 +345,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect('env-merge-info', env_merge_info)
     app.connect('env-purge-doc', env_purge_doc)
     app.connect('html-collect-pages', collect_pages)
-    app.connect('missing-reference', missing_reference)
     # app.add_config_value('viewcode_include_modules', [], 'env')
     # app.add_config_value('viewcode_exclude_modules', [], 'env')
     app.add_event('viewcode-find-source')
@@ -374,5 +353,5 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     return {
         'version': sphinx.__display_version__,
         'env_version': 1,
-        'parallel_read_safe': True
+        'parallel_read_safe': True,
     }
diff --git a/docs/lite/api/requirements.txt b/docs/lite/api/requirements.txt
index 7b4ba238b6cb2cb3748fcca3126f487094e06c57..6bb4d15e79dca58f5b69645cf92306cd3c7911d0 100644
--- a/docs/lite/api/requirements.txt
+++ b/docs/lite/api/requirements.txt
@@ -1,7 +1,7 @@
-sphinx == 4.4.0
-docutils == 0.17.1
-myst-parser == 0.18.1
-sphinx_rtd_theme == 1.0.0
+sphinx == 7.0.1
+docutils == 0.20.1
+myst-parser == 2.0.0
+sphinx_rtd_theme == 3.0.0
 exhale == 0.2.3
 breathe == 4.35.0
 numpy
diff --git a/docs/lite/api/source_en/conf.py b/docs/lite/api/source_en/conf.py
index 408e41a12c0d7928efab0d519b43b62841af0b91..d09f992a5b0f39372136b6ac82e5acbbbabfc174 100644
--- a/docs/lite/api/source_en/conf.py
+++ b/docs/lite/api/source_en/conf.py
@@ -247,12 +247,10 @@ exhale_args = {
 # Fix some dl-label lack class='simple'
 from docutils.writers import _html_base
 
-with open(_html_base.__file__, "r+", encoding="utf-8") as f:
+with open(_html_base.__file__, "r", encoding="utf-8") as f:
     code_str = f.read()
-    old_str = '''        if self.is_compactable(node):
-            classes.append('simple')'''
-    new_str = '''        if classes == []:
-            classes.append('simple')'''
+    old_str = "classes = ['simple'] if self.is_compactable(node) else []"
+    new_str = "classes = ['simple']"
     code_str = code_str.replace(old_str, new_str)
     exec(code_str, _html_base.__dict__)
 
@@ -482,5 +480,5 @@ for file_name in fileList:
 #     with open(file_name2, 'w', encoding='utf-8') as p:
 #         p.write(file_data2)
 
-sys.path.append(os.path.abspath('../../../../resource/search'))
-import search_code
+# sys.path.append(os.path.abspath('../../../../resource/search'))
+# import search_code
diff --git a/docs/lite/api/source_zh_cn/conf.py b/docs/lite/api/source_zh_cn/conf.py
index 57ffe8f2c28ac4766e2d1f4ee27001f3582e1ea5..9544f4e2568e477236897f98666b4d0c87185522 100644
--- a/docs/lite/api/source_zh_cn/conf.py
+++ b/docs/lite/api/source_zh_cn/conf.py
@@ -99,12 +99,10 @@ from custom_directives import IncludeCodeDirective
 # Fix some dl-label lack class='simple'
 from docutils.writers import _html_base
 
-with open(_html_base.__file__, "r+", encoding="utf-8") as f:
+with open(_html_base.__file__, "r", encoding="utf-8") as f:
     code_str = f.read()
-    old_str = '''        if self.is_compactable(node):
-            classes.append('simple')'''
-    new_str = '''        if classes == []:
-            classes.append('simple')'''
+    old_str = "classes = ['simple'] if self.is_compactable(node) else []"
+    new_str = "classes = ['simple']"
     code_str = code_str.replace(old_str, new_str)
     exec(code_str, _html_base.__dict__)
 
@@ -276,8 +274,8 @@ import mindspore_lite
 sys.path.append(os.path.abspath('../../../../resource/sphinx_ext'))
 # import anchor_mod
 
-sys.path.append(os.path.abspath('../../../../resource/search'))
-import search_code
+# sys.path.append(os.path.abspath('../../../../resource/search'))
+# import search_code
 
 
 
diff --git a/docs/mindearth/docs/_ext/customdocumenter.txt b/docs/mindearth/docs/_ext/customdocumenter.txt
index 2d37ae41f6772a21da2a7dc5c7bff75128e68330..505ed7c57e6d7a30d106ca7a33111df6a8278ad3 100644
--- a/docs/mindearth/docs/_ext/customdocumenter.txt
+++ b/docs/mindearth/docs/_ext/customdocumenter.txt
@@ -8,7 +8,7 @@ class CustomDocumenter(Documenter):
     def document_members(self, all_members: bool = False) -> None:
         """Generate reST for member documentation.
 
-        If *all_members* is True, do all members, else those given by
+        If *all_members* is True, document all members, else those given by
         *self.options.members*.
         """
         # set current namespace for finding members
@@ -16,8 +16,9 @@ class CustomDocumenter(Documenter):
         if self.objpath:
             self.env.temp_data['autodoc:class'] = self.objpath[0]
 
-        want_all = all_members or self.options.inherited_members or \
-            self.options.members is ALL
+        want_all = (all_members or
+                    self.options.inherited_members or
+                    self.options.members is ALL)
         # find out which members are documentable
         members_check_module, members = self.get_object_members(want_all)
 
@@ -59,7 +60,7 @@ class CustomDocumenter(Documenter):
             ]
 
         # document non-skipped members
-        memberdocumenters = []  # type: List[Tuple[Documenter, bool]]
+        memberdocumenters: list[tuple[Documenter, bool]] = []
         for (mname, member, isattr) in self.filter_members(members, want_all):
             classes = [cls for cls in self.documenters.values()
                        if cls.can_document_member(member, mname, isattr, self)]
@@ -111,7 +112,7 @@ class CustomDocumenter(Documenter):
         if not self.parse_name():
             # need a module to import
             logger.warning(
-                __('don\'t know which module to import for autodocumenting '
+                __("don't know which module to import for autodocumenting "
                    '%r (try placing a "module" or "currentmodule" directive '
                    'in the document, or giving an explicit module name)') %
                 self.name, type='autodoc')
@@ -126,7 +127,8 @@ class CustomDocumenter(Documenter):
         # where the attribute documentation would actually be found in.
         # This is used for situations where you have a module that collects the
         # functions and classes of internal submodules.
-        self.real_modname = real_modname or self.get_real_modname()  # type: str
+        guess_modname = self.get_real_modname()
+        self.real_modname: str = real_modname or guess_modname
 
         # try to also get a source code analyzer for attribute docs
         try:
@@ -134,15 +136,28 @@ class CustomDocumenter(Documenter):
             # parse right now, to get PycodeErrors on parsing (results will
             # be cached anyway)
             self.analyzer.find_attr_docs()
-        except PycodeError as err:
-            logger.debug('[autodoc] module analyzer failed: %s', err)
+        except PycodeError as exc:
+            logger.debug('[autodoc] module analyzer failed: %s', exc)
             # no source file -- e.g. for builtin and C modules
             self.analyzer = None
             # at least add the module.__file__ as a dependency
             if hasattr(self.module, '__file__') and self.module.__file__:
-                self.directive.filename_set.add(self.module.__file__)
+                self.directive.record_dependencies.add(self.module.__file__)
         else:
-            self.directive.filename_set.add(self.analyzer.srcname)
+            self.directive.record_dependencies.add(self.analyzer.srcname)
+
+        if self.real_modname != guess_modname:
+            # Add module to dependency list if target object is defined in other module.
+            try:
+                analyzer = ModuleAnalyzer.for_module(guess_modname)
+                self.directive.record_dependencies.add(analyzer.srcname)
+            except PycodeError:
+                pass
+
+        docstrings: list[str] = sum(self.get_doc() or [], [])
+        if ismock(self.object) and not docstrings:
+            logger.warning(__('A mocked object is detected: %r'),
+                           self.name, type='autodoc')
 
         # check __module__ of object (for members not given explicitly)
         if check_module:
@@ -160,29 +175,41 @@ class ModuleDocumenter(CustomDocumenter):
     objtype = 'module'
     content_indent = ''
     titles_allowed = True
+    _extra_indent = '   '
 
-    option_spec = {
+    option_spec: OptionSpec = {
         'members': members_option, 'undoc-members': bool_option,
-        'noindex': bool_option, 'inherited-members': bool_option,
+        'noindex': bool_option, 'inherited-members': inherited_members_option,
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
-        'member-order': identity, 'exclude-members': members_set_option,
-        'private-members': bool_option, 'special-members': members_option,
-        'imported-members': bool_option, 'ignore-module-all': bool_option
-    }  # type: Dict[str, Callable]
+        'member-order': member_order_option, 'exclude-members': exclude_members_option,
+        'private-members': members_option, 'special-members': members_option,
+        'imported-members': bool_option, 'ignore-module-all': bool_option,
+        'no-value': bool_option,
+    }
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
         merge_members_option(self.options)
+        self.__all__: Sequence[str] | None = None
+
+    def add_content(self, more_content: StringList | None) -> None:
+        old_indent = self.indent
+        self.indent += self._extra_indent
+        super().add_content(None)
+        self.indent = old_indent
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         # don't document submodules automatically
         return False
 
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         if modname is not None:
             logger.warning(__('"::" in automodule name doesn\'t make sense'),
                            type='autodoc')
@@ -196,6 +223,20 @@ class ModuleDocumenter(CustomDocumenter):
                            type='autodoc')
         return ret
 
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+
+        try:
+            if not self.options.ignore_module_all:
+                self.__all__ = inspect.getall(self.object)
+        except ValueError as exc:
+            # invalid __all__ found.
+            logger.warning(__('__all__ should be a list of strings, not %r '
+                              '(in module %s) -- ignoring __all__') %
+                           (exc.args[0], self.fullname), type='autodoc')
+
+        return ret
+
     def add_directive_header(self, sig: str) -> None:
         Documenter.add_directive_header(self, sig)
 
@@ -209,37 +250,57 @@ class ModuleDocumenter(CustomDocumenter):
         if self.options.deprecated:
             self.add_line('   :deprecated:', sourcename)
 
-    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, object]]]:
+    def get_module_members(self) -> dict[str, ObjectMember]:
+        """Get members of target module."""
+        if self.analyzer:
+            attr_docs = self.analyzer.attr_docs
+        else:
+            attr_docs = {}
+
+        members: dict[str, ObjectMember] = {}
+        for name in dir(self.object):
+            try:
+                value = safe_getattr(self.object, name, None)
+                if ismock(value):
+                    value = undecorate(value)
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, value, docstring="\n".join(docstring))
+            except AttributeError:
+                continue
+
+        # annotation only member (ex. attr: int)
+        for name in inspect.getannotations(self.object):
+            if name not in members:
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, INSTANCEATTR,
+                                             docstring="\n".join(docstring))
+
+        return members
+
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        members = self.get_module_members()
         if want_all:
             if (self.options.ignore_module_all or not
                     hasattr(self.object, '__all__')):
                 # for implicit module members, check __module__ to avoid
                 # documenting imported objects
-                return True, get_module_members(self.object)
+                return True, list(members.values())
             else:
-                memberlist = self.object.__all__
-                # Sometimes __all__ is broken...
-                if not isinstance(memberlist, (list, tuple)) or not \
-                   all(isinstance(entry, str) for entry in memberlist):
-                    logger.warning(
-                        __('__all__ should be a list of strings, not %r '
-                           '(in module %s) -- ignoring __all__') %
-                        (memberlist, self.fullname),
-                        type='autodoc'
-                    )
-                    # fall back to all members
-                    return True, get_module_members(self.object)
+                for member in members.values():
+                    if member.__name__ not in self.__all__:
+                        member.skipped = True
+
+                # fall back to all members
+                return True,  list(members.values())
         else:
             memberlist = self.options.members or []
-        ret = []
-        for mname in memberlist:
-            try:
-                ret.append((mname, safe_getattr(self.object, mname)))
-            except AttributeError:
-                logger.warning(
-                    __('missing attribute mentioned in :members: or __all__: '
-                       'module %s, attribute %s') %
-                    (safe_getattr(self.object, '__name__', '???'), mname),
-                    type='autodoc'
-                )
-        return False, ret
+            ret = []
+            for name in memberlist:
+                if name in members:
+                    ret.append(members[name])
+                else:
+                    logger.warning(__('missing attribute mentioned in :members: option: '
+                                      'module %s, attribute %s') %
+                                   (safe_getattr(self.object, '__name__', '???'), name),
+                                   type='autodoc')
+            return False, ret
diff --git a/docs/mindearth/docs/_ext/overwriteautosummary_generate.txt b/docs/mindearth/docs/_ext/overwriteautosummary_generate.txt
index 4b0a1b1dd2b410ecab971b13da9993c90d65ef0d..23a4c166e123413b21d42f4eeab1accbc09b4896 100644
--- a/docs/mindearth/docs/_ext/overwriteautosummary_generate.txt
+++ b/docs/mindearth/docs/_ext/overwriteautosummary_generate.txt
@@ -1,22 +1,19 @@
-"""
-    sphinx.ext.autosummary.generate
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Usable as a library or script to generate automatic RST source files for
-    items referred to in autosummary:: directives.
+"""Generates reST source files for autosummary.
 
-    Each generated RST file contains a single auto*:: directive which
-    extracts the docstring of the referred item.
+Usable as a library or script to generate automatic RST source files for
+items referred to in autosummary:: directives.
 
-    Example Makefile rule::
+Each generated RST file contains a single auto*:: directive which
+extracts the docstring of the referred item.
 
-       generate:
-               sphinx-autogen -o source/generated source/*.rst
+Example Makefile rule::
 
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+   generate:
+           sphinx-autogen -o source/generated source/*.rst
 """
 
+from __future__ import annotations
+
 import argparse
 import importlib
 import inspect
@@ -26,10 +23,8 @@ import pkgutil
 import pydoc
 import re
 import sys
-import warnings
-from gettext import NullTranslations
 from os import path
-from typing import Any, Dict, List, NamedTuple, Sequence, Set, Tuple, Type, Union
+from typing import TYPE_CHECKING, Any, NamedTuple, Sequence
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -39,11 +34,14 @@ from sphinx import __display_version__, package_dir
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import Config
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.ext.autodoc import Documenter
 from sphinx.ext.autodoc.importer import import_module
-from sphinx.ext.autosummary import (ImportExceptionGroup, get_documenter, import_by_name,
-                                    import_ivar_by_name)
+from sphinx.ext.autosummary import (
+    ImportExceptionGroup,
+    get_documenter,
+    import_by_name,
+    import_ivar_by_name,
+)
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.registry import SphinxComponentRegistry
@@ -52,6 +50,9 @@ from sphinx.util.inspect import getall, safe_getattr
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxTemplateLoader
 
+if TYPE_CHECKING:
+    from gettext import NullTranslations
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,7 +62,7 @@ class DummyApplication:
     def __init__(self, translator: NullTranslations) -> None:
         self.config = Config()
         self.registry = SphinxComponentRegistry()
-        self.messagelog: List[str] = []
+        self.messagelog: list[str] = []
         self.srcdir = "/"
         self.translator = translator
         self.verbosity = 0
@@ -91,32 +92,26 @@ class AutosummaryEntry(NamedTuple):
 
 
 def setup_documenters(app: Any) -> None:
-    from sphinx.ext.autodoc import (AttributeDocumenter, ClassDocumenter, DataDocumenter,
-                                    DecoratorDocumenter, ExceptionDocumenter,
-                                    FunctionDocumenter, MethodDocumenter, ModuleDocumenter,
-                                    NewTypeAttributeDocumenter, NewTypeDataDocumenter,
-                                    PropertyDocumenter)
-    documenters: List[Type[Documenter]] = [
+    from sphinx.ext.autodoc import (
+        AttributeDocumenter,
+        ClassDocumenter,
+        DataDocumenter,
+        DecoratorDocumenter,
+        ExceptionDocumenter,
+        FunctionDocumenter,
+        MethodDocumenter,
+        ModuleDocumenter,
+        PropertyDocumenter,
+    )
+    documenters: list[type[Documenter]] = [
         ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter,
-        FunctionDocumenter, MethodDocumenter, NewTypeAttributeDocumenter,
-        NewTypeDataDocumenter, AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
+        FunctionDocumenter, MethodDocumenter,
+        AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
     ]
     for documenter in documenters:
         app.registry.add_documenter(documenter.objtype, documenter)
 
 
-def _simple_info(msg: str) -> None:
-    warnings.warn('_simple_info() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print(msg)
-
-
-def _simple_warn(msg: str) -> None:
-    warnings.warn('_simple_warn() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print('WARNING: ' + msg, file=sys.stderr)
-
-
 def _underline(title: str, line: str = '=') -> str:
     if '\n' in title:
         raise ValueError('Can only underline single lines')
@@ -126,14 +121,9 @@ def _underline(title: str, line: str = '=') -> str:
 class AutosummaryRenderer:
     """A helper class for rendering."""
 
-    def __init__(self, app: Union[Builder, Sphinx], template_dir: str = None) -> None:
+    def __init__(self, app: Sphinx) -> None:
         if isinstance(app, Builder):
-            warnings.warn('The first argument for AutosummaryRenderer has been '
-                          'changed to Sphinx object',
-                          RemovedInSphinx50Warning, stacklevel=2)
-        if template_dir:
-            warnings.warn('template_dir argument for AutosummaryRenderer is deprecated.',
-                          RemovedInSphinx50Warning, stacklevel=2)
+            raise ValueError('Expected a Sphinx application object!')
 
         system_templates_path = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')]
         loader = SphinxTemplateLoader(app.srcdir, app.config.templates_path,
@@ -144,26 +134,11 @@ class AutosummaryRenderer:
         self.env.filters['e'] = rst.escape
         self.env.filters['underline'] = _underline
 
-        if isinstance(app, (Sphinx, DummyApplication)):
-            if app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.translator)
-        elif isinstance(app, Builder):
-            if app.app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.app.translator)
-
-    def exists(self, template_name: str) -> bool:
-        """Check if template file exists."""
-        warnings.warn('AutosummaryRenderer.exists() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-        try:
-            self.env.get_template(template_name)
-            return True
-        except TemplateNotFound:
-            return False
+        if app.translator:
+            self.env.add_extension("jinja2.ext.i18n")
+            self.env.install_gettext_translations(app.translator)
 
-    def render(self, template_name: str, context: Dict) -> str:
+    def render(self, template_name: str, context: dict) -> str:
         """Render a template file."""
         try:
             template = self.env.get_template(template_name)
@@ -199,8 +174,14 @@ class ModuleScanner:
                            name, exc, type='autosummary')
             return False
 
-    def scan(self, imported_members: bool) -> List[str]:
+    def scan(self, imported_members: bool) -> list[str]:
         members = []
+        try:
+            analyzer = ModuleAnalyzer.for_module(self.object.__name__)
+            attr_docs = analyzer.find_attr_docs()
+        except PycodeError:
+            attr_docs = {}
+
         for name in members_of(self.object, self.app.config):
             try:
                 value = safe_getattr(self.object, name)
@@ -212,7 +193,9 @@ class ModuleScanner:
                 continue
 
             try:
-                if inspect.ismodule(value):
+                if ('', name) in attr_docs:
+                    imported = False
+                elif inspect.ismodule(value):  # NoQA: SIM114
                     imported = True
                 elif safe_getattr(value, '__module__') != self.object.__name__:
                     imported = True
@@ -222,14 +205,14 @@ class ModuleScanner:
                 imported = False
 
             respect_module_all = not self.app.config.autosummary_ignore_module_all
-            if imported_members:
+            if (
                 # list all members up
-                members.append(name)
-            elif imported is False:
+                imported_members
                 # list not-imported members
-                members.append(name)
-            elif '__all__' in dir(self.object) and respect_module_all:
+                or imported is False
                 # list members that have __all__ set
+                or (respect_module_all and '__all__' in dir(self.object))
+            ):
                 members.append(name)
 
         return members
@@ -249,8 +232,9 @@ def members_of(obj: Any, conf: Config) -> Sequence[str]:
 def generate_autosummary_content(name: str, obj: Any, parent: Any,
                                  template: AutosummaryRenderer, template_name: str,
                                  imported_members: bool, app: Any,
-                                 recursive: bool, context: Dict,
-                                 modname: str = None, qualname: str = None) -> str:
+                                 recursive: bool, context: dict,
+                                 modname: str | None = None,
+                                 qualname: str | None = None) -> str:
     doc = get_documenter(app, obj, parent)
 
     def skip_member(obj: Any, name: str, objtype: str) -> bool:
@@ -263,11 +247,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                            name, exc, type='autosummary')
             return False
 
-    def get_class_members(obj: Any) -> Dict[str, Any]:
+    def get_class_members(obj: Any) -> dict[str, Any]:
         members = sphinx.ext.autodoc.get_class_members(obj, [qualname], safe_getattr)
         return {name: member.object for name, member in members.items()}
 
-    def get_module_members(obj: Any) -> Dict[str, Any]:
+    def get_module_members(obj: Any) -> dict[str, Any]:
         members = {}
         for name in members_of(obj, app.config):
             try:
@@ -276,17 +260,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 continue
         return members
 
-    def get_all_members(obj: Any) -> Dict[str, Any]:
+    def get_all_members(obj: Any) -> dict[str, Any]:
         if doc.objtype == "module":
             return get_module_members(obj)
         elif doc.objtype == "class":
             return get_class_members(obj)
         return {}
 
-    def get_members(obj: Any, types: Set[str], include_public: List[str] = [],
-                    imported: bool = True) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
-        public: List[str] = []
+    def get_members(obj: Any, types: set[str], include_public: list[str] = [],
+                    imported: bool = True) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
 
         all_members = get_all_members(obj)
         for name, value in all_members.items():
@@ -308,7 +292,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                             public.append(name)
         return public, items
 
-    def get_module_attrs(members: Any) -> Tuple[List[str], List[str]]:
+    def get_module_attrs(members: Any) -> tuple[list[str], list[str]]:
         """Find module attributes with docstrings."""
         attrs, public = [], []
         try:
@@ -323,9 +307,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             pass    # give up if ModuleAnalyzer fails to parse code
         return public, attrs
 
-    def get_modules(obj: Any) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
+    def get_modules(
+            obj: Any,
+            skip: Sequence[str],
+            public_members: Sequence[str] | None = None) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
         for _, modname, _ispkg in pkgutil.iter_modules(obj.__path__):
+
+            if modname in skip:
+                # module was overwritten in __init__.py, so not accessible
+                continue
             fullname = name + '.' + modname
             try:
                 module = import_module(fullname)
@@ -335,15 +327,24 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 pass
 
             items.append(fullname)
-        public = [x for x in items if not x.split('.')[-1].startswith('_')]
+            if public_members is not None:
+                if modname in public_members:
+                    public.append(fullname)
+            else:
+                if not modname.startswith('_'):
+                    public.append(fullname)
         return public, items
 
-    ns: Dict[str, Any] = {}
+    ns: dict[str, Any] = {}
     ns.update(context)
 
     if doc.objtype == 'module':
         scanner = ModuleScanner(app, obj)
         ns['members'] = scanner.scan(imported_members)
+
+        respect_module_all = not app.config.autosummary_ignore_module_all
+        imported_members = imported_members or ('__all__' in dir(obj) and respect_module_all)
+
         ns['functions'], ns['all_functions'] = \
             get_members(obj, {'function'}, imported=imported_members)
         ns['classes'], ns['all_classes'] = \
@@ -354,7 +355,36 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             get_module_attrs(ns['members'])
         ispackage = hasattr(obj, '__path__')
         if ispackage and recursive:
-            ns['modules'], ns['all_modules'] = get_modules(obj)
+            # Use members that are not modules as skip list, because it would then mean
+            # that module was overwritten in the package namespace
+            skip = (
+                ns["all_functions"]
+                + ns["all_classes"]
+                + ns["all_exceptions"]
+                + ns["all_attributes"]
+            )
+
+            # If respect_module_all and module has a __all__ attribute, first get
+            # modules that were explicitly imported. Next, find the rest with the
+            # get_modules method, but only put in "public" modules that are in the
+            # __all__ list
+            #
+            # Otherwise, use get_modules method normally
+            if respect_module_all and '__all__' in dir(obj):
+                imported_modules, all_imported_modules = \
+                    get_members(obj, {'module'}, imported=True)
+                skip += all_imported_modules
+                imported_modules = [name + '.' + modname for modname in imported_modules]
+                all_imported_modules = \
+                    [name + '.' + modname for modname in all_imported_modules]
+                public_members = getall(obj)
+            else:
+                imported_modules, all_imported_modules = [], []
+                public_members = None
+
+            modules, all_modules = get_modules(obj, skip=skip, public_members=public_members)
+            ns['modules'] = imported_modules + modules
+            ns["all_modules"] = all_imported_modules + all_modules
     elif doc.objtype == 'class':
         ns['members'] = dir(obj)
         ns['inherited_members'] = \
@@ -389,21 +419,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         return template.render(doc.objtype, ns)
 
 
-def generate_autosummary_docs(sources: List[str], output_dir: str = None,
-                              suffix: str = '.rst', base_path: str = None,
-                              builder: Builder = None, template_dir: str = None,
+def generate_autosummary_docs(sources: list[str], output_dir: str | None = None,
+                              suffix: str = '.rst', base_path: str | None = None,
                               imported_members: bool = False, app: Any = None,
                               overwrite: bool = True, encoding: str = 'utf-8') -> None:
-
-    if builder:
-        warnings.warn('builder argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    if template_dir:
-        warnings.warn('template_dir argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    showed_sources = list(sorted(sources))
+    showed_sources = sorted(sources)
     if len(showed_sources) > 20:
         showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:]
     logger.info(__('[autosummary] generating autosummary for: %s') %
@@ -439,7 +459,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
         ensuredir(path)
 
         try:
-            name, obj, parent, modname = import_by_name(entry.name, grouped_exception=True)
+            name, obj, parent, modname = import_by_name(entry.name)
             qualname = name.replace(modname + ".", "")
         except ImportExceptionGroup as exc:
             try:
@@ -448,16 +468,16 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
                 qualname = name.replace(modname + ".", "")
             except ImportError as exc2:
                 if exc2.__cause__:
-                    exceptions: List[BaseException] = exc.exceptions + [exc2.__cause__]
+                    exceptions: list[BaseException] = exc.exceptions + [exc2.__cause__]
                 else:
                     exceptions = exc.exceptions + [exc2]
 
-                errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exceptions))
+                errors = list({f"* {type(e).__name__}: {e}" for e in exceptions})
                 logger.warning(__('[autosummary] failed to import %s.\nPossible hints:\n%s'),
                                entry.name, '\n'.join(errors))
                 continue
 
-        context: Dict[str, Any] = {}
+        context: dict[str, Any] = {}
         if app:
             context.update(app.config.autosummary_context)
 
@@ -484,7 +504,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
 
             if content == old_content:
                 continue
-            elif overwrite:  # content has changed
+            if overwrite:  # content has changed
                 with open(filename, 'w', encoding=encoding) as f:
                     f.write(content)
                 new_files.append(filename)
@@ -497,19 +517,18 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     if new_files:
         generate_autosummary_docs(new_files, output_dir=output_dir,
                                   suffix=suffix, base_path=base_path,
-                                  builder=builder, template_dir=template_dir,
                                   imported_members=imported_members, app=app,
                                   overwrite=overwrite)
 
 
 # -- Finding documented entries in files ---------------------------------------
 
-def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
+def find_autosummary_in_files(filenames: list[str]) -> list[AutosummaryEntry]:
     """Find out what items are documented in source/*.rst.
 
     See `find_autosummary_in_lines`.
     """
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
     for filename in filenames:
         with open(filename, encoding='utf-8', errors='ignore') as f:
             lines = f.read().splitlines()
@@ -517,33 +536,31 @@ def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
     return documented
 
 
-def find_autosummary_in_docstring(name: str, module: str = None, filename: str = None
-                                  ) -> List[AutosummaryEntry]:
+def find_autosummary_in_docstring(
+    name: str, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items are documented in the given object's docstring.
 
     See `find_autosummary_in_lines`.
     """
-    if module:
-        warnings.warn('module argument for find_autosummary_in_docstring() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
     try:
-        real_name, obj, parent, modname = import_by_name(name, grouped_exception=True)
+        real_name, obj, parent, modname = import_by_name(name)
         lines = pydoc.getdoc(obj).splitlines()
         return find_autosummary_in_lines(lines, module=name, filename=filename)
     except AttributeError:
         pass
     except ImportExceptionGroup as exc:
-        errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exc.exceptions))
-        print('Failed to import %s.\nPossible hints:\n%s' % (name, '\n'.join(errors)))
+        errors = '\n'.join({f"* {type(e).__name__}: {e}" for e in exc.exceptions})
+        print(f'Failed to import {name}.\nPossible hints:\n{errors}')
     except SystemExit:
         print("Failed to import '%s'; the module executes module level "
               "statement and it might call sys.exit()." % name)
     return []
 
 
-def find_autosummary_in_lines(lines: List[str], module: str = None, filename: str = None
-                              ) -> List[AutosummaryEntry]:
+def find_autosummary_in_lines(
+    lines: list[str], module: str | None = None, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items appear in autosummary:: directives in the
     given lines.
 
@@ -564,10 +581,10 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
     toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$')
     template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$')
 
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
 
     recursive = False
-    toctree: str = None
+    toctree: str | None = None
     template = None
     current_module = module
     in_autosummary = False
@@ -603,7 +620,7 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
                     name = name[1:]
                 if current_module and \
                    not name.startswith(current_module + '.'):
-                    name = "%s.%s" % (current_module, name)
+                    name = f"{current_module}.{name}"
                 documented.append(AutosummaryEntry(name, toctree, template, recursive))
                 continue
 
@@ -683,12 +700,11 @@ The format of the autosummary directive is documented in the
     return parser
 
 
-def main(argv: List[str] = sys.argv[1:]) -> None:
-    sphinx.locale.setlocale(locale.LC_ALL, '')
-    sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
-    translator, _ = sphinx.locale.init([], None)
+def main(argv: list[str] = sys.argv[1:]) -> None:
+    locale.setlocale(locale.LC_ALL, '')
+    sphinx.locale.init_console()
 
-    app = DummyApplication(translator)
+    app = DummyApplication(sphinx.locale.get_translator())
     logging.setup(app, sys.stdout, sys.stderr)  # type: ignore
     setup_documenters(app)
     args = get_parser().parse_args(argv)
diff --git a/docs/mindearth/docs/_ext/overwriteobjectiondirective.txt b/docs/mindearth/docs/_ext/overwriteobjectiondirective.txt
index f551652f1a09c8a6178a2c04ffb8141eb98ef9df..2774703f812669d94823b280fec7e58a045fe465 100644
--- a/docs/mindearth/docs/_ext/overwriteobjectiondirective.txt
+++ b/docs/mindearth/docs/_ext/overwriteobjectiondirective.txt
@@ -1,17 +1,11 @@
-"""
-    sphinx.directives
-    ~~~~~~~~~~~~~~~~~
+"""Handlers for additional ReST directives."""
 
-    Handlers for additional ReST directives.
-
-    :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import re
 import inspect
 import importlib
-from typing import TYPE_CHECKING, Any, Dict, Generic, List, Tuple, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, List, TypeVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -19,10 +13,10 @@ from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
 from sphinx.addnodes import desc_signature
-from sphinx.deprecation import RemovedInSphinx50Warning, deprecated_alias
 from sphinx.util import docutils, logging
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
@@ -33,7 +27,7 @@ if TYPE_CHECKING:
 nl_escape_re = re.compile(r'\\\n')
 strip_backslash_re = re.compile(r'\\(.)')
 
-T = TypeVar('T')
+ObjDescT = TypeVar('ObjDescT')
 logger = logging.getLogger(__name__)
 
 def optional_int(argument: str) -> int:
@@ -90,7 +84,7 @@ def get_platforms(name: str):
     except:
         return []
 
-class ObjectDescription(SphinxDirective, Generic[T]):
+class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     """
     Directive to describe a class, function or similar object.  Not used
     directly, but subclassed (in domain-specific directives) to add custom
@@ -103,18 +97,20 @@ class ObjectDescription(SphinxDirective, Generic[T]):
     final_argument_whitespace = True
     option_spec: OptionSpec = {
         'noindex': directives.flag,
-    }  # type: Dict[str, DirectiveOption]
+        'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
+    }
 
     # types of doc fields that this directive handles, see sphinx.util.docfields
-    doc_field_types: List[Field] = []
-    domain: str = None
-    objtype: str = None
-    indexnode: addnodes.index = None
+    doc_field_types: list[Field] = []
+    domain: str | None = None
+    objtype: str  # set when `run` method is called
+    indexnode: addnodes.index
 
     # Warning: this might be removed in future version. Don't touch this from extensions.
-    _doc_field_type_map = {}  # type: Dict[str, Tuple[Field, bool]]
+    _doc_field_type_map: dict[str, tuple[Field, bool]] = {}
 
-    def get_field_type_map(self) -> Dict[str, Tuple[Field, bool]]:
+    def get_field_type_map(self) -> dict[str, tuple[Field, bool]]:
         if self._doc_field_type_map == {}:
             self._doc_field_type_map = {}
             for field in self.doc_field_types:
@@ -128,12 +124,10 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         return self._doc_field_type_map
 
-    def get_signatures(self) -> List[str]:
+    def get_signatures(self) -> list[str]:
         """
         Retrieve the signatures to document from the directive arguments.  By
         default, signatures are given as arguments, one per line.
-
-        Backslash-escaping of newlines is supported.
         """
         lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
         if self.config.strip_signature_backslash:
@@ -142,7 +136,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         else:
             return [line.strip() for line in lines]
 
-    def handle_signature(self, sig: str, signode: desc_signature) -> Any:
+    def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
         """
         Parse the signature *sig* into individual nodes and append them to
         *signode*. If ValueError is raised, parsing is aborted and the whole
@@ -154,7 +148,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         """
         raise ValueError
 
-    def add_target_and_index(self, name: Any, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -197,7 +191,45 @@ class ObjectDescription(SphinxDirective, Generic[T]):
             ls.append((rst_file, start_num+i))
         return ls
 
-    def run(self) -> List[Node]:
+    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
+        """
+        Returns a tuple of strings, one entry for each part of the object's
+        hierarchy (e.g. ``('module', 'submodule', 'Class', 'method')``). The
+        returned tuple is used to properly nest children within parents in the
+        table of contents, and can also be used within the
+        :py:meth:`_toc_entry_name` method.
+
+        This method must not be used outwith table of contents generation.
+        """
+        return ()
+
+    def _toc_entry_name(self, sig_node: desc_signature) -> str:
+        """
+        Returns the text of the table of contents entry for the object.
+
+        This function is called once, in :py:meth:`run`, to set the name for the
+        table of contents entry (a special attribute ``_toc_name`` is set on the
+        object node, later used in
+        ``environment.collectors.toctree.TocTreeCollector.process_doc().build_toc()``
+        when the table of contents entries are collected).
+
+        To support table of contents entries for their objects, domains must
+        override this method, also respecting the configuration setting
+        ``toc_object_entries_show_parents``. Domains must also override
+        :py:meth:`_object_hierarchy_parts`, with one (string) entry for each part of the
+        object's hierarchy. The result of this method is set on the signature
+        node, and can be accessed as ``sig_node['_toc_parts']`` for use within
+        this method. The resulting tuple is also used to properly nest children
+        within parents in the table of contents.
+
+        An example implementations of this method is within the python domain
+        (:meth:`!PyObject._toc_entry_name`). The python domain sets the
+        ``_toc_parts`` attribute within the :py:meth:`handle_signature()`
+        method.
+        """
+        return ''
+
+    def run(self) -> list[Node]:
         """
         Main directive entry function, called by docutils upon encountering the
         directive.
@@ -223,15 +255,28 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         node = addnodes.desc()
         node.document = self.state.document
+        source, line = self.get_source_info()
+        # If any options were specified to the directive,
+        # self.state.document.current_line will at this point be set to
+        # None.  To ensure nodes created as part of the signature have a line
+        # number set, set the document's line number correctly.
+        #
+        # Note that we need to subtract one from the line number since
+        # note_source uses 0-based line numbers.
+        if line is not None:
+            line -= 1
+        self.state.document.note_source(source, line)
         node['domain'] = self.domain
         # 'desctype' is a backwards compatible attribute
         node['objtype'] = node['desctype'] = self.objtype
         node['noindex'] = noindex = ('noindex' in self.options)
+        node['noindexentry'] = ('noindexentry' in self.options)
+        node['nocontentsentry'] = ('nocontentsentry' in self.options)
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
 
-        self.names: List[T] = []
+        self.names: list[ObjDescT] = []
         signatures = self.get_signatures()
         for sig in signatures:
             # add a signature node for each signature in the current unit
@@ -249,6 +294,15 @@ class ObjectDescription(SphinxDirective, Generic[T]):
                 signode.clear()
                 signode += addnodes.desc_name(sig, sig)
                 continue  # we don't want an index entry here
+            finally:
+                # Private attributes for ToC generation. Will be modified or removed
+                # without notice.
+                if self.env.app.config.toc_object_entries:
+                    signode['_toc_parts'] = self._object_hierarchy_parts(signode)
+                    signode['_toc_name'] = self._toc_entry_name(signode)
+                else:
+                    signode['_toc_parts'] = ()
+                    signode['_toc_name'] = ''
             if name not in self.names:
                 self.names.append(name)
                 if not noindex:
@@ -290,7 +344,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
             self.content.items.extend(self.extend_items(self.content.items[0][0], self.content.items[-1][1], len(extra)))
         except Exception as e:
             logger.warning(f'{e}')
-        self.state.nested_parse(self.content, self.content_offset, contentnode)
+        nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
         self.transform_content(contentnode)
         self.env.app.emit('object-description-transform',
                           self.domain, self.objtype, contentnode)
@@ -308,14 +362,14 @@ class DefaultRole(SphinxDirective):
     optional_arguments = 1
     final_argument_whitespace = False
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         if not self.arguments:
             docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
         role, messages = roles.role(role_name, self.state_machine.language,
                                     self.lineno, self.state.reporter)
-        if role:
+        if role:  # type: ignore[truthy-function]
             docutils.register_role('', role)
             self.env.temp_data['default_role'] = role_name
         else:
@@ -337,9 +391,9 @@ class DefaultDomain(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()
         # if domain_name not in env.domains:
         #     # try searching by label
@@ -350,7 +404,8 @@ class DefaultDomain(SphinxDirective):
         self.env.temp_data['default_domain'] = self.env.domains.get(domain_name)
         return []
 
-def setup(app: "Sphinx") -> Dict[str, Any]:
+
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value("strip_signature_backslash", False, 'env')
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)
diff --git a/docs/mindearth/docs/_ext/overwriteviewcode.txt b/docs/mindearth/docs/_ext/overwriteviewcode.txt
index 84640d524131abde9a829bc02242894561c5e603..a2fdcfb787bb99e6d96742574675f79151a4848d 100644
--- a/docs/mindearth/docs/_ext/overwriteviewcode.txt
+++ b/docs/mindearth/docs/_ext/overwriteviewcode.txt
@@ -1,18 +1,12 @@
-"""
-    sphinx.ext.viewcode
-    ~~~~~~~~~~~~~~~~~~~
+"""Add links to module code in Python object descriptions."""
 
-    Add links to module code in Python object descriptions.
-
-    :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import posixpath
 import traceback
 import warnings
 from os import path
-from typing import Any, Dict, Generator, Iterable, Optional, Set, Tuple, cast
+from typing import Any, Generator, Iterable, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
@@ -22,12 +16,12 @@ from sphinx import addnodes
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import get_full_modname, logging, status_iterator
+from sphinx.util import get_full_modname, logging
+from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
 
 
@@ -46,13 +40,13 @@ class viewcode_anchor(Element):
     """
 
 
-def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str]:
+def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> str | None:
     try:
         return get_full_modname(modname, attribute)
     except AttributeError:
         # sphinx.ext.viewcode can't follow class instance attribute
         # then AttributeError logging output only verbose mode.
-        logger.verbose('Didn\'t find %s in %s', attribute, modname)
+        logger.verbose("Didn't find %s in %s", attribute, modname)
         return None
     except Exception as e:
         # sphinx.ext.viewcode follow python domain directives.
@@ -67,12 +61,11 @@ def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str
 def is_supported_builder(builder: Builder) -> bool:
     if builder.format != 'html':
         return False
-    elif builder.name == 'singlehtml':
+    if builder.name == 'singlehtml':
         return False
-    elif builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
+    if builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
         return False
-    else:
-        return True
+    return True
 
 
 def doctree_read(app: Sphinx, doctree: Node) -> None:
@@ -112,7 +105,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
     for objnode in list(doctree.findall(addnodes.desc)):
         if objnode.get('domain') != 'py':
             continue
-        names: Set[str] = set()
+        names: set[str] = set()
         for signode in objnode:
             if not isinstance(signode, addnodes.desc_signature):
                 continue
@@ -211,19 +204,7 @@ class ViewcodeAnchorTransform(SphinxPostTransform):
             node.parent.remove(node)
 
 
-def missing_reference(app: Sphinx, env: BuildEnvironment, node: Element, contnode: Node
-                      ) -> Optional[Node]:
-    # resolve our "viewcode" reference nodes -- they need special treatment
-    if node['reftype'] == 'viewcode':
-        warnings.warn('viewcode extension is no longer use pending_xref node. '
-                      'Please update your extension.', RemovedInSphinx50Warning)
-        return make_refnode(app.builder, node['refdoc'], node['reftarget'],
-                            node['refid'], contnode)
-
-    return None
-
-
-def get_module_filename(app: Sphinx, modname: str) -> Optional[str]:
+def get_module_filename(app: Sphinx, modname: str) -> str | None:
     """Get module filename for *modname*."""
     source_info = app.emit_firstresult('viewcode-find-source', modname)
     if source_info:
@@ -251,13 +232,13 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
         if path.getmtime(module_filename) <= path.getmtime(page_filename):
             # generation is not needed if the HTML page is newer than module file.
             return False
-    except IOError:
+    except OSError:
         pass
 
     return True
 
 
-def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], None, None]:
+def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], None, None]:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
         return
@@ -282,7 +263,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
         # construct a page name for the highlighted source
         pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))
         # highlight the source using the builder's highlighter
-        if env.config.highlight_language in ('python3', 'default', 'none'):
+        if env.config.highlight_language in {'default', 'none'}:
             lexer = env.config.highlight_language
         else:
             lexer = 'python'
@@ -343,10 +324,9 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
                 stack.pop()
                 html.append('</ul>')
             stack.append(modname + '.')
-        html.append('<li><a href="%s">%s</a></li>\n' % (
-            urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
-                  posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))),
-            modname))
+        relative_uri = urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
+                             posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/')))
+        html.append(f'<li><a href="{relative_uri}">{modname}</a></li>\n')
     html.append('</ul>' * (len(stack) - 1))
     context = {
         'title': _('Overview: module code'),
@@ -357,7 +337,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
     yield (posixpath.join(OUTPUT_DIRNAME, 'index'), context, 'page.html')
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('viewcode_import', None, False)
     app.add_config_value('viewcode_enable_epub', False, False)
     app.add_config_value('viewcode_follow_imported_members', True, False)
@@ -365,7 +345,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect('env-merge-info', env_merge_info)
     app.connect('env-purge-doc', env_purge_doc)
     app.connect('html-collect-pages', collect_pages)
-    app.connect('missing-reference', missing_reference)
     # app.add_config_value('viewcode_include_modules', [], 'env')
     # app.add_config_value('viewcode_exclude_modules', [], 'env')
     app.add_event('viewcode-find-source')
@@ -374,5 +353,5 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     return {
         'version': sphinx.__display_version__,
         'env_version': 1,
-        'parallel_read_safe': True
+        'parallel_read_safe': True,
     }
diff --git a/docs/mindearth/docs/requirements.txt b/docs/mindearth/docs/requirements.txt
index d0e9823ca3f3b89d6ef24e72e44ecd381eed6786..c45dfaaea15d727930a01217c3cde4c08013f03c 100644
--- a/docs/mindearth/docs/requirements.txt
+++ b/docs/mindearth/docs/requirements.txt
@@ -1,7 +1,7 @@
-sphinx == 4.4.0
-docutils == 0.17.1
-myst-parser == 0.18.1
-sphinx_rtd_theme == 1.0.0
+sphinx == 7.0.1
+docutils == 0.20.1
+myst-parser == 2.0.0
+sphinx_rtd_theme == 3.0.0
 numpy
 nbsphinx == 0.8.11
 IPython
diff --git a/docs/mindflow/docs/_ext/customdocumenter.txt b/docs/mindflow/docs/_ext/customdocumenter.txt
index 2d37ae41f6772a21da2a7dc5c7bff75128e68330..505ed7c57e6d7a30d106ca7a33111df6a8278ad3 100644
--- a/docs/mindflow/docs/_ext/customdocumenter.txt
+++ b/docs/mindflow/docs/_ext/customdocumenter.txt
@@ -8,7 +8,7 @@ class CustomDocumenter(Documenter):
     def document_members(self, all_members: bool = False) -> None:
         """Generate reST for member documentation.
 
-        If *all_members* is True, do all members, else those given by
+        If *all_members* is True, document all members, else those given by
         *self.options.members*.
         """
         # set current namespace for finding members
@@ -16,8 +16,9 @@ class CustomDocumenter(Documenter):
         if self.objpath:
             self.env.temp_data['autodoc:class'] = self.objpath[0]
 
-        want_all = all_members or self.options.inherited_members or \
-            self.options.members is ALL
+        want_all = (all_members or
+                    self.options.inherited_members or
+                    self.options.members is ALL)
         # find out which members are documentable
         members_check_module, members = self.get_object_members(want_all)
 
@@ -59,7 +60,7 @@ class CustomDocumenter(Documenter):
             ]
 
         # document non-skipped members
-        memberdocumenters = []  # type: List[Tuple[Documenter, bool]]
+        memberdocumenters: list[tuple[Documenter, bool]] = []
         for (mname, member, isattr) in self.filter_members(members, want_all):
             classes = [cls for cls in self.documenters.values()
                        if cls.can_document_member(member, mname, isattr, self)]
@@ -111,7 +112,7 @@ class CustomDocumenter(Documenter):
         if not self.parse_name():
             # need a module to import
             logger.warning(
-                __('don\'t know which module to import for autodocumenting '
+                __("don't know which module to import for autodocumenting "
                    '%r (try placing a "module" or "currentmodule" directive '
                    'in the document, or giving an explicit module name)') %
                 self.name, type='autodoc')
@@ -126,7 +127,8 @@ class CustomDocumenter(Documenter):
         # where the attribute documentation would actually be found in.
         # This is used for situations where you have a module that collects the
         # functions and classes of internal submodules.
-        self.real_modname = real_modname or self.get_real_modname()  # type: str
+        guess_modname = self.get_real_modname()
+        self.real_modname: str = real_modname or guess_modname
 
         # try to also get a source code analyzer for attribute docs
         try:
@@ -134,15 +136,28 @@ class CustomDocumenter(Documenter):
             # parse right now, to get PycodeErrors on parsing (results will
             # be cached anyway)
             self.analyzer.find_attr_docs()
-        except PycodeError as err:
-            logger.debug('[autodoc] module analyzer failed: %s', err)
+        except PycodeError as exc:
+            logger.debug('[autodoc] module analyzer failed: %s', exc)
             # no source file -- e.g. for builtin and C modules
             self.analyzer = None
             # at least add the module.__file__ as a dependency
             if hasattr(self.module, '__file__') and self.module.__file__:
-                self.directive.filename_set.add(self.module.__file__)
+                self.directive.record_dependencies.add(self.module.__file__)
         else:
-            self.directive.filename_set.add(self.analyzer.srcname)
+            self.directive.record_dependencies.add(self.analyzer.srcname)
+
+        if self.real_modname != guess_modname:
+            # Add module to dependency list if target object is defined in other module.
+            try:
+                analyzer = ModuleAnalyzer.for_module(guess_modname)
+                self.directive.record_dependencies.add(analyzer.srcname)
+            except PycodeError:
+                pass
+
+        docstrings: list[str] = sum(self.get_doc() or [], [])
+        if ismock(self.object) and not docstrings:
+            logger.warning(__('A mocked object is detected: %r'),
+                           self.name, type='autodoc')
 
         # check __module__ of object (for members not given explicitly)
         if check_module:
@@ -160,29 +175,41 @@ class ModuleDocumenter(CustomDocumenter):
     objtype = 'module'
     content_indent = ''
     titles_allowed = True
+    _extra_indent = '   '
 
-    option_spec = {
+    option_spec: OptionSpec = {
         'members': members_option, 'undoc-members': bool_option,
-        'noindex': bool_option, 'inherited-members': bool_option,
+        'noindex': bool_option, 'inherited-members': inherited_members_option,
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
-        'member-order': identity, 'exclude-members': members_set_option,
-        'private-members': bool_option, 'special-members': members_option,
-        'imported-members': bool_option, 'ignore-module-all': bool_option
-    }  # type: Dict[str, Callable]
+        'member-order': member_order_option, 'exclude-members': exclude_members_option,
+        'private-members': members_option, 'special-members': members_option,
+        'imported-members': bool_option, 'ignore-module-all': bool_option,
+        'no-value': bool_option,
+    }
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
         merge_members_option(self.options)
+        self.__all__: Sequence[str] | None = None
+
+    def add_content(self, more_content: StringList | None) -> None:
+        old_indent = self.indent
+        self.indent += self._extra_indent
+        super().add_content(None)
+        self.indent = old_indent
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         # don't document submodules automatically
         return False
 
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         if modname is not None:
             logger.warning(__('"::" in automodule name doesn\'t make sense'),
                            type='autodoc')
@@ -196,6 +223,20 @@ class ModuleDocumenter(CustomDocumenter):
                            type='autodoc')
         return ret
 
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+
+        try:
+            if not self.options.ignore_module_all:
+                self.__all__ = inspect.getall(self.object)
+        except ValueError as exc:
+            # invalid __all__ found.
+            logger.warning(__('__all__ should be a list of strings, not %r '
+                              '(in module %s) -- ignoring __all__') %
+                           (exc.args[0], self.fullname), type='autodoc')
+
+        return ret
+
     def add_directive_header(self, sig: str) -> None:
         Documenter.add_directive_header(self, sig)
 
@@ -209,37 +250,57 @@ class ModuleDocumenter(CustomDocumenter):
         if self.options.deprecated:
             self.add_line('   :deprecated:', sourcename)
 
-    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, object]]]:
+    def get_module_members(self) -> dict[str, ObjectMember]:
+        """Get members of target module."""
+        if self.analyzer:
+            attr_docs = self.analyzer.attr_docs
+        else:
+            attr_docs = {}
+
+        members: dict[str, ObjectMember] = {}
+        for name in dir(self.object):
+            try:
+                value = safe_getattr(self.object, name, None)
+                if ismock(value):
+                    value = undecorate(value)
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, value, docstring="\n".join(docstring))
+            except AttributeError:
+                continue
+
+        # annotation only member (ex. attr: int)
+        for name in inspect.getannotations(self.object):
+            if name not in members:
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, INSTANCEATTR,
+                                             docstring="\n".join(docstring))
+
+        return members
+
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        members = self.get_module_members()
         if want_all:
             if (self.options.ignore_module_all or not
                     hasattr(self.object, '__all__')):
                 # for implicit module members, check __module__ to avoid
                 # documenting imported objects
-                return True, get_module_members(self.object)
+                return True, list(members.values())
             else:
-                memberlist = self.object.__all__
-                # Sometimes __all__ is broken...
-                if not isinstance(memberlist, (list, tuple)) or not \
-                   all(isinstance(entry, str) for entry in memberlist):
-                    logger.warning(
-                        __('__all__ should be a list of strings, not %r '
-                           '(in module %s) -- ignoring __all__') %
-                        (memberlist, self.fullname),
-                        type='autodoc'
-                    )
-                    # fall back to all members
-                    return True, get_module_members(self.object)
+                for member in members.values():
+                    if member.__name__ not in self.__all__:
+                        member.skipped = True
+
+                # fall back to all members
+                return True,  list(members.values())
         else:
             memberlist = self.options.members or []
-        ret = []
-        for mname in memberlist:
-            try:
-                ret.append((mname, safe_getattr(self.object, mname)))
-            except AttributeError:
-                logger.warning(
-                    __('missing attribute mentioned in :members: or __all__: '
-                       'module %s, attribute %s') %
-                    (safe_getattr(self.object, '__name__', '???'), mname),
-                    type='autodoc'
-                )
-        return False, ret
+            ret = []
+            for name in memberlist:
+                if name in members:
+                    ret.append(members[name])
+                else:
+                    logger.warning(__('missing attribute mentioned in :members: option: '
+                                      'module %s, attribute %s') %
+                                   (safe_getattr(self.object, '__name__', '???'), name),
+                                   type='autodoc')
+            return False, ret
diff --git a/docs/mindflow/docs/_ext/overwriteautosummary_generate.txt b/docs/mindflow/docs/_ext/overwriteautosummary_generate.txt
index 4b0a1b1dd2b410ecab971b13da9993c90d65ef0d..23a4c166e123413b21d42f4eeab1accbc09b4896 100644
--- a/docs/mindflow/docs/_ext/overwriteautosummary_generate.txt
+++ b/docs/mindflow/docs/_ext/overwriteautosummary_generate.txt
@@ -1,22 +1,19 @@
-"""
-    sphinx.ext.autosummary.generate
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Usable as a library or script to generate automatic RST source files for
-    items referred to in autosummary:: directives.
+"""Generates reST source files for autosummary.
 
-    Each generated RST file contains a single auto*:: directive which
-    extracts the docstring of the referred item.
+Usable as a library or script to generate automatic RST source files for
+items referred to in autosummary:: directives.
 
-    Example Makefile rule::
+Each generated RST file contains a single auto*:: directive which
+extracts the docstring of the referred item.
 
-       generate:
-               sphinx-autogen -o source/generated source/*.rst
+Example Makefile rule::
 
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+   generate:
+           sphinx-autogen -o source/generated source/*.rst
 """
 
+from __future__ import annotations
+
 import argparse
 import importlib
 import inspect
@@ -26,10 +23,8 @@ import pkgutil
 import pydoc
 import re
 import sys
-import warnings
-from gettext import NullTranslations
 from os import path
-from typing import Any, Dict, List, NamedTuple, Sequence, Set, Tuple, Type, Union
+from typing import TYPE_CHECKING, Any, NamedTuple, Sequence
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -39,11 +34,14 @@ from sphinx import __display_version__, package_dir
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import Config
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.ext.autodoc import Documenter
 from sphinx.ext.autodoc.importer import import_module
-from sphinx.ext.autosummary import (ImportExceptionGroup, get_documenter, import_by_name,
-                                    import_ivar_by_name)
+from sphinx.ext.autosummary import (
+    ImportExceptionGroup,
+    get_documenter,
+    import_by_name,
+    import_ivar_by_name,
+)
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.registry import SphinxComponentRegistry
@@ -52,6 +50,9 @@ from sphinx.util.inspect import getall, safe_getattr
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxTemplateLoader
 
+if TYPE_CHECKING:
+    from gettext import NullTranslations
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,7 +62,7 @@ class DummyApplication:
     def __init__(self, translator: NullTranslations) -> None:
         self.config = Config()
         self.registry = SphinxComponentRegistry()
-        self.messagelog: List[str] = []
+        self.messagelog: list[str] = []
         self.srcdir = "/"
         self.translator = translator
         self.verbosity = 0
@@ -91,32 +92,26 @@ class AutosummaryEntry(NamedTuple):
 
 
 def setup_documenters(app: Any) -> None:
-    from sphinx.ext.autodoc import (AttributeDocumenter, ClassDocumenter, DataDocumenter,
-                                    DecoratorDocumenter, ExceptionDocumenter,
-                                    FunctionDocumenter, MethodDocumenter, ModuleDocumenter,
-                                    NewTypeAttributeDocumenter, NewTypeDataDocumenter,
-                                    PropertyDocumenter)
-    documenters: List[Type[Documenter]] = [
+    from sphinx.ext.autodoc import (
+        AttributeDocumenter,
+        ClassDocumenter,
+        DataDocumenter,
+        DecoratorDocumenter,
+        ExceptionDocumenter,
+        FunctionDocumenter,
+        MethodDocumenter,
+        ModuleDocumenter,
+        PropertyDocumenter,
+    )
+    documenters: list[type[Documenter]] = [
         ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter,
-        FunctionDocumenter, MethodDocumenter, NewTypeAttributeDocumenter,
-        NewTypeDataDocumenter, AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
+        FunctionDocumenter, MethodDocumenter,
+        AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
     ]
     for documenter in documenters:
         app.registry.add_documenter(documenter.objtype, documenter)
 
 
-def _simple_info(msg: str) -> None:
-    warnings.warn('_simple_info() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print(msg)
-
-
-def _simple_warn(msg: str) -> None:
-    warnings.warn('_simple_warn() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print('WARNING: ' + msg, file=sys.stderr)
-
-
 def _underline(title: str, line: str = '=') -> str:
     if '\n' in title:
         raise ValueError('Can only underline single lines')
@@ -126,14 +121,9 @@ def _underline(title: str, line: str = '=') -> str:
 class AutosummaryRenderer:
     """A helper class for rendering."""
 
-    def __init__(self, app: Union[Builder, Sphinx], template_dir: str = None) -> None:
+    def __init__(self, app: Sphinx) -> None:
         if isinstance(app, Builder):
-            warnings.warn('The first argument for AutosummaryRenderer has been '
-                          'changed to Sphinx object',
-                          RemovedInSphinx50Warning, stacklevel=2)
-        if template_dir:
-            warnings.warn('template_dir argument for AutosummaryRenderer is deprecated.',
-                          RemovedInSphinx50Warning, stacklevel=2)
+            raise ValueError('Expected a Sphinx application object!')
 
         system_templates_path = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')]
         loader = SphinxTemplateLoader(app.srcdir, app.config.templates_path,
@@ -144,26 +134,11 @@ class AutosummaryRenderer:
         self.env.filters['e'] = rst.escape
         self.env.filters['underline'] = _underline
 
-        if isinstance(app, (Sphinx, DummyApplication)):
-            if app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.translator)
-        elif isinstance(app, Builder):
-            if app.app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.app.translator)
-
-    def exists(self, template_name: str) -> bool:
-        """Check if template file exists."""
-        warnings.warn('AutosummaryRenderer.exists() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-        try:
-            self.env.get_template(template_name)
-            return True
-        except TemplateNotFound:
-            return False
+        if app.translator:
+            self.env.add_extension("jinja2.ext.i18n")
+            self.env.install_gettext_translations(app.translator)
 
-    def render(self, template_name: str, context: Dict) -> str:
+    def render(self, template_name: str, context: dict) -> str:
         """Render a template file."""
         try:
             template = self.env.get_template(template_name)
@@ -199,8 +174,14 @@ class ModuleScanner:
                            name, exc, type='autosummary')
             return False
 
-    def scan(self, imported_members: bool) -> List[str]:
+    def scan(self, imported_members: bool) -> list[str]:
         members = []
+        try:
+            analyzer = ModuleAnalyzer.for_module(self.object.__name__)
+            attr_docs = analyzer.find_attr_docs()
+        except PycodeError:
+            attr_docs = {}
+
         for name in members_of(self.object, self.app.config):
             try:
                 value = safe_getattr(self.object, name)
@@ -212,7 +193,9 @@ class ModuleScanner:
                 continue
 
             try:
-                if inspect.ismodule(value):
+                if ('', name) in attr_docs:
+                    imported = False
+                elif inspect.ismodule(value):  # NoQA: SIM114
                     imported = True
                 elif safe_getattr(value, '__module__') != self.object.__name__:
                     imported = True
@@ -222,14 +205,14 @@ class ModuleScanner:
                 imported = False
 
             respect_module_all = not self.app.config.autosummary_ignore_module_all
-            if imported_members:
+            if (
                 # list all members up
-                members.append(name)
-            elif imported is False:
+                imported_members
                 # list not-imported members
-                members.append(name)
-            elif '__all__' in dir(self.object) and respect_module_all:
+                or imported is False
                 # list members that have __all__ set
+                or (respect_module_all and '__all__' in dir(self.object))
+            ):
                 members.append(name)
 
         return members
@@ -249,8 +232,9 @@ def members_of(obj: Any, conf: Config) -> Sequence[str]:
 def generate_autosummary_content(name: str, obj: Any, parent: Any,
                                  template: AutosummaryRenderer, template_name: str,
                                  imported_members: bool, app: Any,
-                                 recursive: bool, context: Dict,
-                                 modname: str = None, qualname: str = None) -> str:
+                                 recursive: bool, context: dict,
+                                 modname: str | None = None,
+                                 qualname: str | None = None) -> str:
     doc = get_documenter(app, obj, parent)
 
     def skip_member(obj: Any, name: str, objtype: str) -> bool:
@@ -263,11 +247,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                            name, exc, type='autosummary')
             return False
 
-    def get_class_members(obj: Any) -> Dict[str, Any]:
+    def get_class_members(obj: Any) -> dict[str, Any]:
         members = sphinx.ext.autodoc.get_class_members(obj, [qualname], safe_getattr)
         return {name: member.object for name, member in members.items()}
 
-    def get_module_members(obj: Any) -> Dict[str, Any]:
+    def get_module_members(obj: Any) -> dict[str, Any]:
         members = {}
         for name in members_of(obj, app.config):
             try:
@@ -276,17 +260,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 continue
         return members
 
-    def get_all_members(obj: Any) -> Dict[str, Any]:
+    def get_all_members(obj: Any) -> dict[str, Any]:
         if doc.objtype == "module":
             return get_module_members(obj)
         elif doc.objtype == "class":
             return get_class_members(obj)
         return {}
 
-    def get_members(obj: Any, types: Set[str], include_public: List[str] = [],
-                    imported: bool = True) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
-        public: List[str] = []
+    def get_members(obj: Any, types: set[str], include_public: list[str] = [],
+                    imported: bool = True) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
 
         all_members = get_all_members(obj)
         for name, value in all_members.items():
@@ -308,7 +292,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                             public.append(name)
         return public, items
 
-    def get_module_attrs(members: Any) -> Tuple[List[str], List[str]]:
+    def get_module_attrs(members: Any) -> tuple[list[str], list[str]]:
         """Find module attributes with docstrings."""
         attrs, public = [], []
         try:
@@ -323,9 +307,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             pass    # give up if ModuleAnalyzer fails to parse code
         return public, attrs
 
-    def get_modules(obj: Any) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
+    def get_modules(
+            obj: Any,
+            skip: Sequence[str],
+            public_members: Sequence[str] | None = None) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
         for _, modname, _ispkg in pkgutil.iter_modules(obj.__path__):
+
+            if modname in skip:
+                # module was overwritten in __init__.py, so not accessible
+                continue
             fullname = name + '.' + modname
             try:
                 module = import_module(fullname)
@@ -335,15 +327,24 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 pass
 
             items.append(fullname)
-        public = [x for x in items if not x.split('.')[-1].startswith('_')]
+            if public_members is not None:
+                if modname in public_members:
+                    public.append(fullname)
+            else:
+                if not modname.startswith('_'):
+                    public.append(fullname)
         return public, items
 
-    ns: Dict[str, Any] = {}
+    ns: dict[str, Any] = {}
     ns.update(context)
 
     if doc.objtype == 'module':
         scanner = ModuleScanner(app, obj)
         ns['members'] = scanner.scan(imported_members)
+
+        respect_module_all = not app.config.autosummary_ignore_module_all
+        imported_members = imported_members or ('__all__' in dir(obj) and respect_module_all)
+
         ns['functions'], ns['all_functions'] = \
             get_members(obj, {'function'}, imported=imported_members)
         ns['classes'], ns['all_classes'] = \
@@ -354,7 +355,36 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             get_module_attrs(ns['members'])
         ispackage = hasattr(obj, '__path__')
         if ispackage and recursive:
-            ns['modules'], ns['all_modules'] = get_modules(obj)
+            # Use members that are not modules as skip list, because it would then mean
+            # that module was overwritten in the package namespace
+            skip = (
+                ns["all_functions"]
+                + ns["all_classes"]
+                + ns["all_exceptions"]
+                + ns["all_attributes"]
+            )
+
+            # If respect_module_all and module has a __all__ attribute, first get
+            # modules that were explicitly imported. Next, find the rest with the
+            # get_modules method, but only put in "public" modules that are in the
+            # __all__ list
+            #
+            # Otherwise, use get_modules method normally
+            if respect_module_all and '__all__' in dir(obj):
+                imported_modules, all_imported_modules = \
+                    get_members(obj, {'module'}, imported=True)
+                skip += all_imported_modules
+                imported_modules = [name + '.' + modname for modname in imported_modules]
+                all_imported_modules = \
+                    [name + '.' + modname for modname in all_imported_modules]
+                public_members = getall(obj)
+            else:
+                imported_modules, all_imported_modules = [], []
+                public_members = None
+
+            modules, all_modules = get_modules(obj, skip=skip, public_members=public_members)
+            ns['modules'] = imported_modules + modules
+            ns["all_modules"] = all_imported_modules + all_modules
     elif doc.objtype == 'class':
         ns['members'] = dir(obj)
         ns['inherited_members'] = \
@@ -389,21 +419,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         return template.render(doc.objtype, ns)
 
 
-def generate_autosummary_docs(sources: List[str], output_dir: str = None,
-                              suffix: str = '.rst', base_path: str = None,
-                              builder: Builder = None, template_dir: str = None,
+def generate_autosummary_docs(sources: list[str], output_dir: str | None = None,
+                              suffix: str = '.rst', base_path: str | None = None,
                               imported_members: bool = False, app: Any = None,
                               overwrite: bool = True, encoding: str = 'utf-8') -> None:
-
-    if builder:
-        warnings.warn('builder argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    if template_dir:
-        warnings.warn('template_dir argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    showed_sources = list(sorted(sources))
+    showed_sources = sorted(sources)
     if len(showed_sources) > 20:
         showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:]
     logger.info(__('[autosummary] generating autosummary for: %s') %
@@ -439,7 +459,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
         ensuredir(path)
 
         try:
-            name, obj, parent, modname = import_by_name(entry.name, grouped_exception=True)
+            name, obj, parent, modname = import_by_name(entry.name)
             qualname = name.replace(modname + ".", "")
         except ImportExceptionGroup as exc:
             try:
@@ -448,16 +468,16 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
                 qualname = name.replace(modname + ".", "")
             except ImportError as exc2:
                 if exc2.__cause__:
-                    exceptions: List[BaseException] = exc.exceptions + [exc2.__cause__]
+                    exceptions: list[BaseException] = exc.exceptions + [exc2.__cause__]
                 else:
                     exceptions = exc.exceptions + [exc2]
 
-                errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exceptions))
+                errors = list({f"* {type(e).__name__}: {e}" for e in exceptions})
                 logger.warning(__('[autosummary] failed to import %s.\nPossible hints:\n%s'),
                                entry.name, '\n'.join(errors))
                 continue
 
-        context: Dict[str, Any] = {}
+        context: dict[str, Any] = {}
         if app:
             context.update(app.config.autosummary_context)
 
@@ -484,7 +504,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
 
             if content == old_content:
                 continue
-            elif overwrite:  # content has changed
+            if overwrite:  # content has changed
                 with open(filename, 'w', encoding=encoding) as f:
                     f.write(content)
                 new_files.append(filename)
@@ -497,19 +517,18 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     if new_files:
         generate_autosummary_docs(new_files, output_dir=output_dir,
                                   suffix=suffix, base_path=base_path,
-                                  builder=builder, template_dir=template_dir,
                                   imported_members=imported_members, app=app,
                                   overwrite=overwrite)
 
 
 # -- Finding documented entries in files ---------------------------------------
 
-def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
+def find_autosummary_in_files(filenames: list[str]) -> list[AutosummaryEntry]:
     """Find out what items are documented in source/*.rst.
 
     See `find_autosummary_in_lines`.
     """
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
     for filename in filenames:
         with open(filename, encoding='utf-8', errors='ignore') as f:
             lines = f.read().splitlines()
@@ -517,33 +536,31 @@ def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
     return documented
 
 
-def find_autosummary_in_docstring(name: str, module: str = None, filename: str = None
-                                  ) -> List[AutosummaryEntry]:
+def find_autosummary_in_docstring(
+    name: str, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items are documented in the given object's docstring.
 
     See `find_autosummary_in_lines`.
     """
-    if module:
-        warnings.warn('module argument for find_autosummary_in_docstring() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
     try:
-        real_name, obj, parent, modname = import_by_name(name, grouped_exception=True)
+        real_name, obj, parent, modname = import_by_name(name)
         lines = pydoc.getdoc(obj).splitlines()
         return find_autosummary_in_lines(lines, module=name, filename=filename)
     except AttributeError:
         pass
     except ImportExceptionGroup as exc:
-        errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exc.exceptions))
-        print('Failed to import %s.\nPossible hints:\n%s' % (name, '\n'.join(errors)))
+        errors = '\n'.join({f"* {type(e).__name__}: {e}" for e in exc.exceptions})
+        print(f'Failed to import {name}.\nPossible hints:\n{errors}')
     except SystemExit:
         print("Failed to import '%s'; the module executes module level "
               "statement and it might call sys.exit()." % name)
     return []
 
 
-def find_autosummary_in_lines(lines: List[str], module: str = None, filename: str = None
-                              ) -> List[AutosummaryEntry]:
+def find_autosummary_in_lines(
+    lines: list[str], module: str | None = None, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items appear in autosummary:: directives in the
     given lines.
 
@@ -564,10 +581,10 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
     toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$')
     template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$')
 
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
 
     recursive = False
-    toctree: str = None
+    toctree: str | None = None
     template = None
     current_module = module
     in_autosummary = False
@@ -603,7 +620,7 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
                     name = name[1:]
                 if current_module and \
                    not name.startswith(current_module + '.'):
-                    name = "%s.%s" % (current_module, name)
+                    name = f"{current_module}.{name}"
                 documented.append(AutosummaryEntry(name, toctree, template, recursive))
                 continue
 
@@ -683,12 +700,11 @@ The format of the autosummary directive is documented in the
     return parser
 
 
-def main(argv: List[str] = sys.argv[1:]) -> None:
-    sphinx.locale.setlocale(locale.LC_ALL, '')
-    sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
-    translator, _ = sphinx.locale.init([], None)
+def main(argv: list[str] = sys.argv[1:]) -> None:
+    locale.setlocale(locale.LC_ALL, '')
+    sphinx.locale.init_console()
 
-    app = DummyApplication(translator)
+    app = DummyApplication(sphinx.locale.get_translator())
     logging.setup(app, sys.stdout, sys.stderr)  # type: ignore
     setup_documenters(app)
     args = get_parser().parse_args(argv)
diff --git a/docs/mindflow/docs/_ext/overwriteobjectiondirective.txt b/docs/mindflow/docs/_ext/overwriteobjectiondirective.txt
index 8a58bf71191f77ca22097ea9de244c9df5c3d4fb..2774703f812669d94823b280fec7e58a045fe465 100644
--- a/docs/mindflow/docs/_ext/overwriteobjectiondirective.txt
+++ b/docs/mindflow/docs/_ext/overwriteobjectiondirective.txt
@@ -1,17 +1,11 @@
-"""
-    sphinx.directives
-    ~~~~~~~~~~~~~~~~~
+"""Handlers for additional ReST directives."""
 
-    Handlers for additional ReST directives.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import re
 import inspect
 import importlib
-from typing import TYPE_CHECKING, Any, Dict, Generic, List, Tuple, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, List, TypeVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -19,10 +13,10 @@ from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
 from sphinx.addnodes import desc_signature
-from sphinx.deprecation import RemovedInSphinx50Warning, deprecated_alias
 from sphinx.util import docutils, logging
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
@@ -33,7 +27,7 @@ if TYPE_CHECKING:
 nl_escape_re = re.compile(r'\\\n')
 strip_backslash_re = re.compile(r'\\(.)')
 
-T = TypeVar('T')
+ObjDescT = TypeVar('ObjDescT')
 logger = logging.getLogger(__name__)
 
 def optional_int(argument: str) -> int:
@@ -90,7 +84,7 @@ def get_platforms(name: str):
     except:
         return []
 
-class ObjectDescription(SphinxDirective, Generic[T]):
+class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     """
     Directive to describe a class, function or similar object.  Not used
     directly, but subclassed (in domain-specific directives) to add custom
@@ -103,18 +97,20 @@ class ObjectDescription(SphinxDirective, Generic[T]):
     final_argument_whitespace = True
     option_spec: OptionSpec = {
         'noindex': directives.flag,
-    }  # type: Dict[str, DirectiveOption]
+        'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
+    }
 
     # types of doc fields that this directive handles, see sphinx.util.docfields
-    doc_field_types: List[Field] = []
-    domain: str = None
-    objtype: str = None
-    indexnode: addnodes.index = None
+    doc_field_types: list[Field] = []
+    domain: str | None = None
+    objtype: str  # set when `run` method is called
+    indexnode: addnodes.index
 
     # Warning: this might be removed in future version. Don't touch this from extensions.
-    _doc_field_type_map = {}  # type: Dict[str, Tuple[Field, bool]]
+    _doc_field_type_map: dict[str, tuple[Field, bool]] = {}
 
-    def get_field_type_map(self) -> Dict[str, Tuple[Field, bool]]:
+    def get_field_type_map(self) -> dict[str, tuple[Field, bool]]:
         if self._doc_field_type_map == {}:
             self._doc_field_type_map = {}
             for field in self.doc_field_types:
@@ -128,12 +124,10 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         return self._doc_field_type_map
 
-    def get_signatures(self) -> List[str]:
+    def get_signatures(self) -> list[str]:
         """
         Retrieve the signatures to document from the directive arguments.  By
         default, signatures are given as arguments, one per line.
-
-        Backslash-escaping of newlines is supported.
         """
         lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
         if self.config.strip_signature_backslash:
@@ -142,7 +136,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         else:
             return [line.strip() for line in lines]
 
-    def handle_signature(self, sig: str, signode: desc_signature) -> Any:
+    def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
         """
         Parse the signature *sig* into individual nodes and append them to
         *signode*. If ValueError is raised, parsing is aborted and the whole
@@ -154,7 +148,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         """
         raise ValueError
 
-    def add_target_and_index(self, name: Any, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -197,7 +191,45 @@ class ObjectDescription(SphinxDirective, Generic[T]):
             ls.append((rst_file, start_num+i))
         return ls
 
-    def run(self) -> List[Node]:
+    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
+        """
+        Returns a tuple of strings, one entry for each part of the object's
+        hierarchy (e.g. ``('module', 'submodule', 'Class', 'method')``). The
+        returned tuple is used to properly nest children within parents in the
+        table of contents, and can also be used within the
+        :py:meth:`_toc_entry_name` method.
+
+        This method must not be used outwith table of contents generation.
+        """
+        return ()
+
+    def _toc_entry_name(self, sig_node: desc_signature) -> str:
+        """
+        Returns the text of the table of contents entry for the object.
+
+        This function is called once, in :py:meth:`run`, to set the name for the
+        table of contents entry (a special attribute ``_toc_name`` is set on the
+        object node, later used in
+        ``environment.collectors.toctree.TocTreeCollector.process_doc().build_toc()``
+        when the table of contents entries are collected).
+
+        To support table of contents entries for their objects, domains must
+        override this method, also respecting the configuration setting
+        ``toc_object_entries_show_parents``. Domains must also override
+        :py:meth:`_object_hierarchy_parts`, with one (string) entry for each part of the
+        object's hierarchy. The result of this method is set on the signature
+        node, and can be accessed as ``sig_node['_toc_parts']`` for use within
+        this method. The resulting tuple is also used to properly nest children
+        within parents in the table of contents.
+
+        An example implementations of this method is within the python domain
+        (:meth:`!PyObject._toc_entry_name`). The python domain sets the
+        ``_toc_parts`` attribute within the :py:meth:`handle_signature()`
+        method.
+        """
+        return ''
+
+    def run(self) -> list[Node]:
         """
         Main directive entry function, called by docutils upon encountering the
         directive.
@@ -223,15 +255,28 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         node = addnodes.desc()
         node.document = self.state.document
+        source, line = self.get_source_info()
+        # If any options were specified to the directive,
+        # self.state.document.current_line will at this point be set to
+        # None.  To ensure nodes created as part of the signature have a line
+        # number set, set the document's line number correctly.
+        #
+        # Note that we need to subtract one from the line number since
+        # note_source uses 0-based line numbers.
+        if line is not None:
+            line -= 1
+        self.state.document.note_source(source, line)
         node['domain'] = self.domain
         # 'desctype' is a backwards compatible attribute
         node['objtype'] = node['desctype'] = self.objtype
         node['noindex'] = noindex = ('noindex' in self.options)
+        node['noindexentry'] = ('noindexentry' in self.options)
+        node['nocontentsentry'] = ('nocontentsentry' in self.options)
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
 
-        self.names: List[T] = []
+        self.names: list[ObjDescT] = []
         signatures = self.get_signatures()
         for sig in signatures:
             # add a signature node for each signature in the current unit
@@ -249,6 +294,15 @@ class ObjectDescription(SphinxDirective, Generic[T]):
                 signode.clear()
                 signode += addnodes.desc_name(sig, sig)
                 continue  # we don't want an index entry here
+            finally:
+                # Private attributes for ToC generation. Will be modified or removed
+                # without notice.
+                if self.env.app.config.toc_object_entries:
+                    signode['_toc_parts'] = self._object_hierarchy_parts(signode)
+                    signode['_toc_name'] = self._toc_entry_name(signode)
+                else:
+                    signode['_toc_parts'] = ()
+                    signode['_toc_name'] = ''
             if name not in self.names:
                 self.names.append(name)
                 if not noindex:
@@ -290,7 +344,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
             self.content.items.extend(self.extend_items(self.content.items[0][0], self.content.items[-1][1], len(extra)))
         except Exception as e:
             logger.warning(f'{e}')
-        self.state.nested_parse(self.content, self.content_offset, contentnode)
+        nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
         self.transform_content(contentnode)
         self.env.app.emit('object-description-transform',
                           self.domain, self.objtype, contentnode)
@@ -308,14 +362,14 @@ class DefaultRole(SphinxDirective):
     optional_arguments = 1
     final_argument_whitespace = False
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         if not self.arguments:
             docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
         role, messages = roles.role(role_name, self.state_machine.language,
                                     self.lineno, self.state.reporter)
-        if role:
+        if role:  # type: ignore[truthy-function]
             docutils.register_role('', role)
             self.env.temp_data['default_role'] = role_name
         else:
@@ -337,9 +391,9 @@ class DefaultDomain(SphinxDirective):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {}  # type: Dict
+    option_spec: OptionSpec = {}
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()
         # if domain_name not in env.domains:
         #     # try searching by label
@@ -350,7 +404,8 @@ class DefaultDomain(SphinxDirective):
         self.env.temp_data['default_domain'] = self.env.domains.get(domain_name)
         return []
 
-def setup(app: "Sphinx") -> Dict[str, Any]:
+
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value("strip_signature_backslash", False, 'env')
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)
diff --git a/docs/mindflow/docs/_ext/overwriteviewcode.txt b/docs/mindflow/docs/_ext/overwriteviewcode.txt
index 172780ec56b3ed90e7b0add617257a618cf38ee0..a2fdcfb787bb99e6d96742574675f79151a4848d 100644
--- a/docs/mindflow/docs/_ext/overwriteviewcode.txt
+++ b/docs/mindflow/docs/_ext/overwriteviewcode.txt
@@ -1,18 +1,12 @@
-"""
-    sphinx.ext.viewcode
-    ~~~~~~~~~~~~~~~~~~~
+"""Add links to module code in Python object descriptions."""
 
-    Add links to module code in Python object descriptions.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import posixpath
 import traceback
 import warnings
 from os import path
-from typing import Any, Dict, Generator, Iterable, Optional, Set, Tuple, cast
+from typing import Any, Generator, Iterable, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
@@ -22,12 +16,12 @@ from sphinx import addnodes
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import get_full_modname, logging, status_iterator
+from sphinx.util import get_full_modname, logging
+from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
 
 
@@ -46,13 +40,13 @@ class viewcode_anchor(Element):
     """
 
 
-def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str]:
+def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> str | None:
     try:
         return get_full_modname(modname, attribute)
     except AttributeError:
         # sphinx.ext.viewcode can't follow class instance attribute
         # then AttributeError logging output only verbose mode.
-        logger.verbose('Didn\'t find %s in %s', attribute, modname)
+        logger.verbose("Didn't find %s in %s", attribute, modname)
         return None
     except Exception as e:
         # sphinx.ext.viewcode follow python domain directives.
@@ -67,12 +61,11 @@ def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str
 def is_supported_builder(builder: Builder) -> bool:
     if builder.format != 'html':
         return False
-    elif builder.name == 'singlehtml':
+    if builder.name == 'singlehtml':
         return False
-    elif builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
+    if builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
         return False
-    else:
-        return True
+    return True
 
 
 def doctree_read(app: Sphinx, doctree: Node) -> None:
@@ -112,7 +105,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
     for objnode in list(doctree.findall(addnodes.desc)):
         if objnode.get('domain') != 'py':
             continue
-        names: Set[str] = set()
+        names: set[str] = set()
         for signode in objnode:
             if not isinstance(signode, addnodes.desc_signature):
                 continue
@@ -211,19 +204,7 @@ class ViewcodeAnchorTransform(SphinxPostTransform):
             node.parent.remove(node)
 
 
-def missing_reference(app: Sphinx, env: BuildEnvironment, node: Element, contnode: Node
-                      ) -> Optional[Node]:
-    # resolve our "viewcode" reference nodes -- they need special treatment
-    if node['reftype'] == 'viewcode':
-        warnings.warn('viewcode extension is no longer use pending_xref node. '
-                      'Please update your extension.', RemovedInSphinx50Warning)
-        return make_refnode(app.builder, node['refdoc'], node['reftarget'],
-                            node['refid'], contnode)
-
-    return None
-
-
-def get_module_filename(app: Sphinx, modname: str) -> Optional[str]:
+def get_module_filename(app: Sphinx, modname: str) -> str | None:
     """Get module filename for *modname*."""
     source_info = app.emit_firstresult('viewcode-find-source', modname)
     if source_info:
@@ -251,13 +232,13 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
         if path.getmtime(module_filename) <= path.getmtime(page_filename):
             # generation is not needed if the HTML page is newer than module file.
             return False
-    except IOError:
+    except OSError:
         pass
 
     return True
 
 
-def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], None, None]:
+def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], None, None]:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
         return
@@ -282,7 +263,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
         # construct a page name for the highlighted source
         pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))
         # highlight the source using the builder's highlighter
-        if env.config.highlight_language in ('python3', 'default', 'none'):
+        if env.config.highlight_language in {'default', 'none'}:
             lexer = env.config.highlight_language
         else:
             lexer = 'python'
@@ -343,10 +324,9 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
                 stack.pop()
                 html.append('</ul>')
             stack.append(modname + '.')
-        html.append('<li><a href="%s">%s</a></li>\n' % (
-            urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
-                  posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))),
-            modname))
+        relative_uri = urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
+                             posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/')))
+        html.append(f'<li><a href="{relative_uri}">{modname}</a></li>\n')
     html.append('</ul>' * (len(stack) - 1))
     context = {
         'title': _('Overview: module code'),
@@ -357,7 +337,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
     yield (posixpath.join(OUTPUT_DIRNAME, 'index'), context, 'page.html')
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('viewcode_import', None, False)
     app.add_config_value('viewcode_enable_epub', False, False)
     app.add_config_value('viewcode_follow_imported_members', True, False)
@@ -365,7 +345,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect('env-merge-info', env_merge_info)
     app.connect('env-purge-doc', env_purge_doc)
     app.connect('html-collect-pages', collect_pages)
-    app.connect('missing-reference', missing_reference)
     # app.add_config_value('viewcode_include_modules', [], 'env')
     # app.add_config_value('viewcode_exclude_modules', [], 'env')
     app.add_event('viewcode-find-source')
@@ -374,5 +353,5 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     return {
         'version': sphinx.__display_version__,
         'env_version': 1,
-        'parallel_read_safe': True
+        'parallel_read_safe': True,
     }
diff --git a/docs/mindflow/docs/requirements.txt b/docs/mindflow/docs/requirements.txt
index f5ddc521080c312d8b9183f4ec8f7ab44186e930..57ac6e8540bdaec92b0db7b376e45efe0258c84a 100644
--- a/docs/mindflow/docs/requirements.txt
+++ b/docs/mindflow/docs/requirements.txt
@@ -1,7 +1,7 @@
-sphinx == 4.4.0
-docutils == 0.17.1
-myst-parser == 0.18.1
-sphinx_rtd_theme == 1.0.0
+sphinx == 7.0.1
+docutils == 0.20.1
+myst-parser == 2.0.0
+sphinx_rtd_theme == 3.0.0
 numpy
 nbsphinx == 0.8.11
 IPython
diff --git a/docs/mindformers/docs/source_en/conf.py b/docs/mindformers/docs/source_en/conf.py
index 7a6b9b6d149a4ff6f01b498b69af9881d09e5499..f4256a2a6e9c41e214da2f189d3f91f06142bae6 100644
--- a/docs/mindformers/docs/source_en/conf.py
+++ b/docs/mindformers/docs/source_en/conf.py
@@ -21,14 +21,14 @@ import sphinx.ext.autosummary.generate as g
 # Fix some dl-label lack class='simple'
 from docutils.writers import _html_base
 
-with open(_html_base.__file__, "r", encoding="utf-8") as f:
-    code_str = f.read()
-    old_str = '''        if self.is_compactable(node):
-            classes.append('simple')'''
-    new_str = '''        if classes == []:
-            classes.append('simple')'''
-    code_str = code_str.replace(old_str, new_str)
-    exec(code_str, _html_base.__dict__)
+# with open(_html_base.__file__, "r", encoding="utf-8") as f:
+#     code_str = f.read()
+#     old_str = '''        if self.is_compactable(node):
+#             classes.append('simple')'''
+#     new_str = '''        if classes == []:
+#             classes.append('simple')'''
+#     code_str = code_str.replace(old_str, new_str)
+#     exec(code_str, _html_base.__dict__)
 
 # -- Project information -----------------------------------------------------
 
diff --git a/docs/mindquantum/docs/_ext/customdocumenter.txt b/docs/mindquantum/docs/_ext/customdocumenter.txt
index 2d37ae41f6772a21da2a7dc5c7bff75128e68330..505ed7c57e6d7a30d106ca7a33111df6a8278ad3 100644
--- a/docs/mindquantum/docs/_ext/customdocumenter.txt
+++ b/docs/mindquantum/docs/_ext/customdocumenter.txt
@@ -8,7 +8,7 @@ class CustomDocumenter(Documenter):
     def document_members(self, all_members: bool = False) -> None:
         """Generate reST for member documentation.
 
-        If *all_members* is True, do all members, else those given by
+        If *all_members* is True, document all members, else those given by
         *self.options.members*.
         """
         # set current namespace for finding members
@@ -16,8 +16,9 @@ class CustomDocumenter(Documenter):
         if self.objpath:
             self.env.temp_data['autodoc:class'] = self.objpath[0]
 
-        want_all = all_members or self.options.inherited_members or \
-            self.options.members is ALL
+        want_all = (all_members or
+                    self.options.inherited_members or
+                    self.options.members is ALL)
         # find out which members are documentable
         members_check_module, members = self.get_object_members(want_all)
 
@@ -59,7 +60,7 @@ class CustomDocumenter(Documenter):
             ]
 
         # document non-skipped members
-        memberdocumenters = []  # type: List[Tuple[Documenter, bool]]
+        memberdocumenters: list[tuple[Documenter, bool]] = []
         for (mname, member, isattr) in self.filter_members(members, want_all):
             classes = [cls for cls in self.documenters.values()
                        if cls.can_document_member(member, mname, isattr, self)]
@@ -111,7 +112,7 @@ class CustomDocumenter(Documenter):
         if not self.parse_name():
             # need a module to import
             logger.warning(
-                __('don\'t know which module to import for autodocumenting '
+                __("don't know which module to import for autodocumenting "
                    '%r (try placing a "module" or "currentmodule" directive '
                    'in the document, or giving an explicit module name)') %
                 self.name, type='autodoc')
@@ -126,7 +127,8 @@ class CustomDocumenter(Documenter):
         # where the attribute documentation would actually be found in.
         # This is used for situations where you have a module that collects the
         # functions and classes of internal submodules.
-        self.real_modname = real_modname or self.get_real_modname()  # type: str
+        guess_modname = self.get_real_modname()
+        self.real_modname: str = real_modname or guess_modname
 
         # try to also get a source code analyzer for attribute docs
         try:
@@ -134,15 +136,28 @@ class CustomDocumenter(Documenter):
             # parse right now, to get PycodeErrors on parsing (results will
             # be cached anyway)
             self.analyzer.find_attr_docs()
-        except PycodeError as err:
-            logger.debug('[autodoc] module analyzer failed: %s', err)
+        except PycodeError as exc:
+            logger.debug('[autodoc] module analyzer failed: %s', exc)
             # no source file -- e.g. for builtin and C modules
             self.analyzer = None
             # at least add the module.__file__ as a dependency
             if hasattr(self.module, '__file__') and self.module.__file__:
-                self.directive.filename_set.add(self.module.__file__)
+                self.directive.record_dependencies.add(self.module.__file__)
         else:
-            self.directive.filename_set.add(self.analyzer.srcname)
+            self.directive.record_dependencies.add(self.analyzer.srcname)
+
+        if self.real_modname != guess_modname:
+            # Add module to dependency list if target object is defined in other module.
+            try:
+                analyzer = ModuleAnalyzer.for_module(guess_modname)
+                self.directive.record_dependencies.add(analyzer.srcname)
+            except PycodeError:
+                pass
+
+        docstrings: list[str] = sum(self.get_doc() or [], [])
+        if ismock(self.object) and not docstrings:
+            logger.warning(__('A mocked object is detected: %r'),
+                           self.name, type='autodoc')
 
         # check __module__ of object (for members not given explicitly)
         if check_module:
@@ -160,29 +175,41 @@ class ModuleDocumenter(CustomDocumenter):
     objtype = 'module'
     content_indent = ''
     titles_allowed = True
+    _extra_indent = '   '
 
-    option_spec = {
+    option_spec: OptionSpec = {
         'members': members_option, 'undoc-members': bool_option,
-        'noindex': bool_option, 'inherited-members': bool_option,
+        'noindex': bool_option, 'inherited-members': inherited_members_option,
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
-        'member-order': identity, 'exclude-members': members_set_option,
-        'private-members': bool_option, 'special-members': members_option,
-        'imported-members': bool_option, 'ignore-module-all': bool_option
-    }  # type: Dict[str, Callable]
+        'member-order': member_order_option, 'exclude-members': exclude_members_option,
+        'private-members': members_option, 'special-members': members_option,
+        'imported-members': bool_option, 'ignore-module-all': bool_option,
+        'no-value': bool_option,
+    }
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
         merge_members_option(self.options)
+        self.__all__: Sequence[str] | None = None
+
+    def add_content(self, more_content: StringList | None) -> None:
+        old_indent = self.indent
+        self.indent += self._extra_indent
+        super().add_content(None)
+        self.indent = old_indent
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         # don't document submodules automatically
         return False
 
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         if modname is not None:
             logger.warning(__('"::" in automodule name doesn\'t make sense'),
                            type='autodoc')
@@ -196,6 +223,20 @@ class ModuleDocumenter(CustomDocumenter):
                            type='autodoc')
         return ret
 
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+
+        try:
+            if not self.options.ignore_module_all:
+                self.__all__ = inspect.getall(self.object)
+        except ValueError as exc:
+            # invalid __all__ found.
+            logger.warning(__('__all__ should be a list of strings, not %r '
+                              '(in module %s) -- ignoring __all__') %
+                           (exc.args[0], self.fullname), type='autodoc')
+
+        return ret
+
     def add_directive_header(self, sig: str) -> None:
         Documenter.add_directive_header(self, sig)
 
@@ -209,37 +250,57 @@ class ModuleDocumenter(CustomDocumenter):
         if self.options.deprecated:
             self.add_line('   :deprecated:', sourcename)
 
-    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, object]]]:
+    def get_module_members(self) -> dict[str, ObjectMember]:
+        """Get members of target module."""
+        if self.analyzer:
+            attr_docs = self.analyzer.attr_docs
+        else:
+            attr_docs = {}
+
+        members: dict[str, ObjectMember] = {}
+        for name in dir(self.object):
+            try:
+                value = safe_getattr(self.object, name, None)
+                if ismock(value):
+                    value = undecorate(value)
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, value, docstring="\n".join(docstring))
+            except AttributeError:
+                continue
+
+        # annotation only member (ex. attr: int)
+        for name in inspect.getannotations(self.object):
+            if name not in members:
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, INSTANCEATTR,
+                                             docstring="\n".join(docstring))
+
+        return members
+
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        members = self.get_module_members()
         if want_all:
             if (self.options.ignore_module_all or not
                     hasattr(self.object, '__all__')):
                 # for implicit module members, check __module__ to avoid
                 # documenting imported objects
-                return True, get_module_members(self.object)
+                return True, list(members.values())
             else:
-                memberlist = self.object.__all__
-                # Sometimes __all__ is broken...
-                if not isinstance(memberlist, (list, tuple)) or not \
-                   all(isinstance(entry, str) for entry in memberlist):
-                    logger.warning(
-                        __('__all__ should be a list of strings, not %r '
-                           '(in module %s) -- ignoring __all__') %
-                        (memberlist, self.fullname),
-                        type='autodoc'
-                    )
-                    # fall back to all members
-                    return True, get_module_members(self.object)
+                for member in members.values():
+                    if member.__name__ not in self.__all__:
+                        member.skipped = True
+
+                # fall back to all members
+                return True,  list(members.values())
         else:
             memberlist = self.options.members or []
-        ret = []
-        for mname in memberlist:
-            try:
-                ret.append((mname, safe_getattr(self.object, mname)))
-            except AttributeError:
-                logger.warning(
-                    __('missing attribute mentioned in :members: or __all__: '
-                       'module %s, attribute %s') %
-                    (safe_getattr(self.object, '__name__', '???'), mname),
-                    type='autodoc'
-                )
-        return False, ret
+            ret = []
+            for name in memberlist:
+                if name in members:
+                    ret.append(members[name])
+                else:
+                    logger.warning(__('missing attribute mentioned in :members: option: '
+                                      'module %s, attribute %s') %
+                                   (safe_getattr(self.object, '__name__', '???'), name),
+                                   type='autodoc')
+            return False, ret
diff --git a/docs/mindquantum/docs/_ext/overwriteautosummary_generate.txt b/docs/mindquantum/docs/_ext/overwriteautosummary_generate.txt
index 4b0a1b1dd2b410ecab971b13da9993c90d65ef0d..23a4c166e123413b21d42f4eeab1accbc09b4896 100644
--- a/docs/mindquantum/docs/_ext/overwriteautosummary_generate.txt
+++ b/docs/mindquantum/docs/_ext/overwriteautosummary_generate.txt
@@ -1,22 +1,19 @@
-"""
-    sphinx.ext.autosummary.generate
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Usable as a library or script to generate automatic RST source files for
-    items referred to in autosummary:: directives.
+"""Generates reST source files for autosummary.
 
-    Each generated RST file contains a single auto*:: directive which
-    extracts the docstring of the referred item.
+Usable as a library or script to generate automatic RST source files for
+items referred to in autosummary:: directives.
 
-    Example Makefile rule::
+Each generated RST file contains a single auto*:: directive which
+extracts the docstring of the referred item.
 
-       generate:
-               sphinx-autogen -o source/generated source/*.rst
+Example Makefile rule::
 
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+   generate:
+           sphinx-autogen -o source/generated source/*.rst
 """
 
+from __future__ import annotations
+
 import argparse
 import importlib
 import inspect
@@ -26,10 +23,8 @@ import pkgutil
 import pydoc
 import re
 import sys
-import warnings
-from gettext import NullTranslations
 from os import path
-from typing import Any, Dict, List, NamedTuple, Sequence, Set, Tuple, Type, Union
+from typing import TYPE_CHECKING, Any, NamedTuple, Sequence
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -39,11 +34,14 @@ from sphinx import __display_version__, package_dir
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import Config
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.ext.autodoc import Documenter
 from sphinx.ext.autodoc.importer import import_module
-from sphinx.ext.autosummary import (ImportExceptionGroup, get_documenter, import_by_name,
-                                    import_ivar_by_name)
+from sphinx.ext.autosummary import (
+    ImportExceptionGroup,
+    get_documenter,
+    import_by_name,
+    import_ivar_by_name,
+)
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.registry import SphinxComponentRegistry
@@ -52,6 +50,9 @@ from sphinx.util.inspect import getall, safe_getattr
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxTemplateLoader
 
+if TYPE_CHECKING:
+    from gettext import NullTranslations
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,7 +62,7 @@ class DummyApplication:
     def __init__(self, translator: NullTranslations) -> None:
         self.config = Config()
         self.registry = SphinxComponentRegistry()
-        self.messagelog: List[str] = []
+        self.messagelog: list[str] = []
         self.srcdir = "/"
         self.translator = translator
         self.verbosity = 0
@@ -91,32 +92,26 @@ class AutosummaryEntry(NamedTuple):
 
 
 def setup_documenters(app: Any) -> None:
-    from sphinx.ext.autodoc import (AttributeDocumenter, ClassDocumenter, DataDocumenter,
-                                    DecoratorDocumenter, ExceptionDocumenter,
-                                    FunctionDocumenter, MethodDocumenter, ModuleDocumenter,
-                                    NewTypeAttributeDocumenter, NewTypeDataDocumenter,
-                                    PropertyDocumenter)
-    documenters: List[Type[Documenter]] = [
+    from sphinx.ext.autodoc import (
+        AttributeDocumenter,
+        ClassDocumenter,
+        DataDocumenter,
+        DecoratorDocumenter,
+        ExceptionDocumenter,
+        FunctionDocumenter,
+        MethodDocumenter,
+        ModuleDocumenter,
+        PropertyDocumenter,
+    )
+    documenters: list[type[Documenter]] = [
         ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter,
-        FunctionDocumenter, MethodDocumenter, NewTypeAttributeDocumenter,
-        NewTypeDataDocumenter, AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
+        FunctionDocumenter, MethodDocumenter,
+        AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
     ]
     for documenter in documenters:
         app.registry.add_documenter(documenter.objtype, documenter)
 
 
-def _simple_info(msg: str) -> None:
-    warnings.warn('_simple_info() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print(msg)
-
-
-def _simple_warn(msg: str) -> None:
-    warnings.warn('_simple_warn() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print('WARNING: ' + msg, file=sys.stderr)
-
-
 def _underline(title: str, line: str = '=') -> str:
     if '\n' in title:
         raise ValueError('Can only underline single lines')
@@ -126,14 +121,9 @@ def _underline(title: str, line: str = '=') -> str:
 class AutosummaryRenderer:
     """A helper class for rendering."""
 
-    def __init__(self, app: Union[Builder, Sphinx], template_dir: str = None) -> None:
+    def __init__(self, app: Sphinx) -> None:
         if isinstance(app, Builder):
-            warnings.warn('The first argument for AutosummaryRenderer has been '
-                          'changed to Sphinx object',
-                          RemovedInSphinx50Warning, stacklevel=2)
-        if template_dir:
-            warnings.warn('template_dir argument for AutosummaryRenderer is deprecated.',
-                          RemovedInSphinx50Warning, stacklevel=2)
+            raise ValueError('Expected a Sphinx application object!')
 
         system_templates_path = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')]
         loader = SphinxTemplateLoader(app.srcdir, app.config.templates_path,
@@ -144,26 +134,11 @@ class AutosummaryRenderer:
         self.env.filters['e'] = rst.escape
         self.env.filters['underline'] = _underline
 
-        if isinstance(app, (Sphinx, DummyApplication)):
-            if app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.translator)
-        elif isinstance(app, Builder):
-            if app.app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.app.translator)
-
-    def exists(self, template_name: str) -> bool:
-        """Check if template file exists."""
-        warnings.warn('AutosummaryRenderer.exists() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-        try:
-            self.env.get_template(template_name)
-            return True
-        except TemplateNotFound:
-            return False
+        if app.translator:
+            self.env.add_extension("jinja2.ext.i18n")
+            self.env.install_gettext_translations(app.translator)
 
-    def render(self, template_name: str, context: Dict) -> str:
+    def render(self, template_name: str, context: dict) -> str:
         """Render a template file."""
         try:
             template = self.env.get_template(template_name)
@@ -199,8 +174,14 @@ class ModuleScanner:
                            name, exc, type='autosummary')
             return False
 
-    def scan(self, imported_members: bool) -> List[str]:
+    def scan(self, imported_members: bool) -> list[str]:
         members = []
+        try:
+            analyzer = ModuleAnalyzer.for_module(self.object.__name__)
+            attr_docs = analyzer.find_attr_docs()
+        except PycodeError:
+            attr_docs = {}
+
         for name in members_of(self.object, self.app.config):
             try:
                 value = safe_getattr(self.object, name)
@@ -212,7 +193,9 @@ class ModuleScanner:
                 continue
 
             try:
-                if inspect.ismodule(value):
+                if ('', name) in attr_docs:
+                    imported = False
+                elif inspect.ismodule(value):  # NoQA: SIM114
                     imported = True
                 elif safe_getattr(value, '__module__') != self.object.__name__:
                     imported = True
@@ -222,14 +205,14 @@ class ModuleScanner:
                 imported = False
 
             respect_module_all = not self.app.config.autosummary_ignore_module_all
-            if imported_members:
+            if (
                 # list all members up
-                members.append(name)
-            elif imported is False:
+                imported_members
                 # list not-imported members
-                members.append(name)
-            elif '__all__' in dir(self.object) and respect_module_all:
+                or imported is False
                 # list members that have __all__ set
+                or (respect_module_all and '__all__' in dir(self.object))
+            ):
                 members.append(name)
 
         return members
@@ -249,8 +232,9 @@ def members_of(obj: Any, conf: Config) -> Sequence[str]:
 def generate_autosummary_content(name: str, obj: Any, parent: Any,
                                  template: AutosummaryRenderer, template_name: str,
                                  imported_members: bool, app: Any,
-                                 recursive: bool, context: Dict,
-                                 modname: str = None, qualname: str = None) -> str:
+                                 recursive: bool, context: dict,
+                                 modname: str | None = None,
+                                 qualname: str | None = None) -> str:
     doc = get_documenter(app, obj, parent)
 
     def skip_member(obj: Any, name: str, objtype: str) -> bool:
@@ -263,11 +247,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                            name, exc, type='autosummary')
             return False
 
-    def get_class_members(obj: Any) -> Dict[str, Any]:
+    def get_class_members(obj: Any) -> dict[str, Any]:
         members = sphinx.ext.autodoc.get_class_members(obj, [qualname], safe_getattr)
         return {name: member.object for name, member in members.items()}
 
-    def get_module_members(obj: Any) -> Dict[str, Any]:
+    def get_module_members(obj: Any) -> dict[str, Any]:
         members = {}
         for name in members_of(obj, app.config):
             try:
@@ -276,17 +260,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 continue
         return members
 
-    def get_all_members(obj: Any) -> Dict[str, Any]:
+    def get_all_members(obj: Any) -> dict[str, Any]:
         if doc.objtype == "module":
             return get_module_members(obj)
         elif doc.objtype == "class":
             return get_class_members(obj)
         return {}
 
-    def get_members(obj: Any, types: Set[str], include_public: List[str] = [],
-                    imported: bool = True) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
-        public: List[str] = []
+    def get_members(obj: Any, types: set[str], include_public: list[str] = [],
+                    imported: bool = True) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
 
         all_members = get_all_members(obj)
         for name, value in all_members.items():
@@ -308,7 +292,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                             public.append(name)
         return public, items
 
-    def get_module_attrs(members: Any) -> Tuple[List[str], List[str]]:
+    def get_module_attrs(members: Any) -> tuple[list[str], list[str]]:
         """Find module attributes with docstrings."""
         attrs, public = [], []
         try:
@@ -323,9 +307,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             pass    # give up if ModuleAnalyzer fails to parse code
         return public, attrs
 
-    def get_modules(obj: Any) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
+    def get_modules(
+            obj: Any,
+            skip: Sequence[str],
+            public_members: Sequence[str] | None = None) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
         for _, modname, _ispkg in pkgutil.iter_modules(obj.__path__):
+
+            if modname in skip:
+                # module was overwritten in __init__.py, so not accessible
+                continue
             fullname = name + '.' + modname
             try:
                 module = import_module(fullname)
@@ -335,15 +327,24 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 pass
 
             items.append(fullname)
-        public = [x for x in items if not x.split('.')[-1].startswith('_')]
+            if public_members is not None:
+                if modname in public_members:
+                    public.append(fullname)
+            else:
+                if not modname.startswith('_'):
+                    public.append(fullname)
         return public, items
 
-    ns: Dict[str, Any] = {}
+    ns: dict[str, Any] = {}
     ns.update(context)
 
     if doc.objtype == 'module':
         scanner = ModuleScanner(app, obj)
         ns['members'] = scanner.scan(imported_members)
+
+        respect_module_all = not app.config.autosummary_ignore_module_all
+        imported_members = imported_members or ('__all__' in dir(obj) and respect_module_all)
+
         ns['functions'], ns['all_functions'] = \
             get_members(obj, {'function'}, imported=imported_members)
         ns['classes'], ns['all_classes'] = \
@@ -354,7 +355,36 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             get_module_attrs(ns['members'])
         ispackage = hasattr(obj, '__path__')
         if ispackage and recursive:
-            ns['modules'], ns['all_modules'] = get_modules(obj)
+            # Use members that are not modules as skip list, because it would then mean
+            # that module was overwritten in the package namespace
+            skip = (
+                ns["all_functions"]
+                + ns["all_classes"]
+                + ns["all_exceptions"]
+                + ns["all_attributes"]
+            )
+
+            # If respect_module_all and module has a __all__ attribute, first get
+            # modules that were explicitly imported. Next, find the rest with the
+            # get_modules method, but only put in "public" modules that are in the
+            # __all__ list
+            #
+            # Otherwise, use get_modules method normally
+            if respect_module_all and '__all__' in dir(obj):
+                imported_modules, all_imported_modules = \
+                    get_members(obj, {'module'}, imported=True)
+                skip += all_imported_modules
+                imported_modules = [name + '.' + modname for modname in imported_modules]
+                all_imported_modules = \
+                    [name + '.' + modname for modname in all_imported_modules]
+                public_members = getall(obj)
+            else:
+                imported_modules, all_imported_modules = [], []
+                public_members = None
+
+            modules, all_modules = get_modules(obj, skip=skip, public_members=public_members)
+            ns['modules'] = imported_modules + modules
+            ns["all_modules"] = all_imported_modules + all_modules
     elif doc.objtype == 'class':
         ns['members'] = dir(obj)
         ns['inherited_members'] = \
@@ -389,21 +419,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         return template.render(doc.objtype, ns)
 
 
-def generate_autosummary_docs(sources: List[str], output_dir: str = None,
-                              suffix: str = '.rst', base_path: str = None,
-                              builder: Builder = None, template_dir: str = None,
+def generate_autosummary_docs(sources: list[str], output_dir: str | None = None,
+                              suffix: str = '.rst', base_path: str | None = None,
                               imported_members: bool = False, app: Any = None,
                               overwrite: bool = True, encoding: str = 'utf-8') -> None:
-
-    if builder:
-        warnings.warn('builder argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    if template_dir:
-        warnings.warn('template_dir argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    showed_sources = list(sorted(sources))
+    showed_sources = sorted(sources)
     if len(showed_sources) > 20:
         showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:]
     logger.info(__('[autosummary] generating autosummary for: %s') %
@@ -439,7 +459,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
         ensuredir(path)
 
         try:
-            name, obj, parent, modname = import_by_name(entry.name, grouped_exception=True)
+            name, obj, parent, modname = import_by_name(entry.name)
             qualname = name.replace(modname + ".", "")
         except ImportExceptionGroup as exc:
             try:
@@ -448,16 +468,16 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
                 qualname = name.replace(modname + ".", "")
             except ImportError as exc2:
                 if exc2.__cause__:
-                    exceptions: List[BaseException] = exc.exceptions + [exc2.__cause__]
+                    exceptions: list[BaseException] = exc.exceptions + [exc2.__cause__]
                 else:
                     exceptions = exc.exceptions + [exc2]
 
-                errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exceptions))
+                errors = list({f"* {type(e).__name__}: {e}" for e in exceptions})
                 logger.warning(__('[autosummary] failed to import %s.\nPossible hints:\n%s'),
                                entry.name, '\n'.join(errors))
                 continue
 
-        context: Dict[str, Any] = {}
+        context: dict[str, Any] = {}
         if app:
             context.update(app.config.autosummary_context)
 
@@ -484,7 +504,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
 
             if content == old_content:
                 continue
-            elif overwrite:  # content has changed
+            if overwrite:  # content has changed
                 with open(filename, 'w', encoding=encoding) as f:
                     f.write(content)
                 new_files.append(filename)
@@ -497,19 +517,18 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     if new_files:
         generate_autosummary_docs(new_files, output_dir=output_dir,
                                   suffix=suffix, base_path=base_path,
-                                  builder=builder, template_dir=template_dir,
                                   imported_members=imported_members, app=app,
                                   overwrite=overwrite)
 
 
 # -- Finding documented entries in files ---------------------------------------
 
-def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
+def find_autosummary_in_files(filenames: list[str]) -> list[AutosummaryEntry]:
     """Find out what items are documented in source/*.rst.
 
     See `find_autosummary_in_lines`.
     """
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
     for filename in filenames:
         with open(filename, encoding='utf-8', errors='ignore') as f:
             lines = f.read().splitlines()
@@ -517,33 +536,31 @@ def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
     return documented
 
 
-def find_autosummary_in_docstring(name: str, module: str = None, filename: str = None
-                                  ) -> List[AutosummaryEntry]:
+def find_autosummary_in_docstring(
+    name: str, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items are documented in the given object's docstring.
 
     See `find_autosummary_in_lines`.
     """
-    if module:
-        warnings.warn('module argument for find_autosummary_in_docstring() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
     try:
-        real_name, obj, parent, modname = import_by_name(name, grouped_exception=True)
+        real_name, obj, parent, modname = import_by_name(name)
         lines = pydoc.getdoc(obj).splitlines()
         return find_autosummary_in_lines(lines, module=name, filename=filename)
     except AttributeError:
         pass
     except ImportExceptionGroup as exc:
-        errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exc.exceptions))
-        print('Failed to import %s.\nPossible hints:\n%s' % (name, '\n'.join(errors)))
+        errors = '\n'.join({f"* {type(e).__name__}: {e}" for e in exc.exceptions})
+        print(f'Failed to import {name}.\nPossible hints:\n{errors}')
     except SystemExit:
         print("Failed to import '%s'; the module executes module level "
               "statement and it might call sys.exit()." % name)
     return []
 
 
-def find_autosummary_in_lines(lines: List[str], module: str = None, filename: str = None
-                              ) -> List[AutosummaryEntry]:
+def find_autosummary_in_lines(
+    lines: list[str], module: str | None = None, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items appear in autosummary:: directives in the
     given lines.
 
@@ -564,10 +581,10 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
     toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$')
     template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$')
 
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
 
     recursive = False
-    toctree: str = None
+    toctree: str | None = None
     template = None
     current_module = module
     in_autosummary = False
@@ -603,7 +620,7 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
                     name = name[1:]
                 if current_module and \
                    not name.startswith(current_module + '.'):
-                    name = "%s.%s" % (current_module, name)
+                    name = f"{current_module}.{name}"
                 documented.append(AutosummaryEntry(name, toctree, template, recursive))
                 continue
 
@@ -683,12 +700,11 @@ The format of the autosummary directive is documented in the
     return parser
 
 
-def main(argv: List[str] = sys.argv[1:]) -> None:
-    sphinx.locale.setlocale(locale.LC_ALL, '')
-    sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
-    translator, _ = sphinx.locale.init([], None)
+def main(argv: list[str] = sys.argv[1:]) -> None:
+    locale.setlocale(locale.LC_ALL, '')
+    sphinx.locale.init_console()
 
-    app = DummyApplication(translator)
+    app = DummyApplication(sphinx.locale.get_translator())
     logging.setup(app, sys.stdout, sys.stderr)  # type: ignore
     setup_documenters(app)
     args = get_parser().parse_args(argv)
diff --git a/docs/mindquantum/docs/_ext/overwriteobjectiondirective.txt b/docs/mindquantum/docs/_ext/overwriteobjectiondirective.txt
index 7e8d31adbd000f457f45d20031c77edc94071edd..1241f6700a13876be0859325afc4078d637192b8 100644
--- a/docs/mindquantum/docs/_ext/overwriteobjectiondirective.txt
+++ b/docs/mindquantum/docs/_ext/overwriteobjectiondirective.txt
@@ -1,17 +1,11 @@
-"""
-    sphinx.directives
-    ~~~~~~~~~~~~~~~~~
+"""Handlers for additional ReST directives."""
 
-    Handlers for additional ReST directives.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import re
 import inspect
 import importlib
-from typing import TYPE_CHECKING, Any, Dict, Generic, List, Tuple, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, List, TypeVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -19,10 +13,10 @@ from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
 from sphinx.addnodes import desc_signature
-from sphinx.deprecation import RemovedInSphinx50Warning, deprecated_alias
 from sphinx.util import docutils, logging
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.typing import OptionSpec
 
 if TYPE_CHECKING:
@@ -32,11 +26,10 @@ if TYPE_CHECKING:
 # RE to strip backslash escapes
 nl_escape_re = re.compile(r'\\\n')
 strip_backslash_re = re.compile(r'\\(.)')
-
-T = TypeVar('T')
+ObjDescT = TypeVar('ObjDescT')
 logger = logging.getLogger(__name__)
 
-def optional_int(argument):
+def optional_int(argument: str) -> int | None:
     """
     Check for an integer argument or None value; raise ``ValueError`` if not.
     """
@@ -101,7 +94,7 @@ def get_side_effect(name: str):
     except:
         return []
 
-class ObjectDescription(SphinxDirective, Generic[T]):
+class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     """
     Directive to describe a class, function or similar object.  Not used
     directly, but subclassed (in domain-specific directives) to add custom
@@ -114,18 +107,20 @@ class ObjectDescription(SphinxDirective, Generic[T]):
     final_argument_whitespace = True
     option_spec: OptionSpec = {
         'noindex': directives.flag,
+        'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
     }
 
     # types of doc fields that this directive handles, see sphinx.util.docfields
-    doc_field_types: List[Field] = []
-    domain: str = None
-    objtype: str = None
-    indexnode: addnodes.index = None
+    doc_field_types: list[Field] = []
+    domain: str | None = None
+    objtype: str  # set when `run` method is called
+    indexnode: addnodes.index
 
     # Warning: this might be removed in future version. Don't touch this from extensions.
-    _doc_field_type_map: Dict[str, Tuple[Field, bool]] = {}
+    _doc_field_type_map: dict[str, tuple[Field, bool]] = {}
 
-    def get_field_type_map(self) -> Dict[str, Tuple[Field, bool]]:
+    def get_field_type_map(self) -> dict[str, tuple[Field, bool]]:
         if self._doc_field_type_map == {}:
             self._doc_field_type_map = {}
             for field in self.doc_field_types:
@@ -139,12 +134,10 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         return self._doc_field_type_map
 
-    def get_signatures(self) -> List[str]:
+    def get_signatures(self) -> list[str]:
         """
         Retrieve the signatures to document from the directive arguments.  By
         default, signatures are given as arguments, one per line.
-
-        Backslash-escaping of newlines is supported.
         """
         lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
         if self.config.strip_signature_backslash:
@@ -153,7 +146,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         else:
             return [line.strip() for line in lines]
 
-    def handle_signature(self, sig: str, signode: desc_signature) -> T:
+    def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
         """
         Parse the signature *sig* into individual nodes and append them to
         *signode*. If ValueError is raised, parsing is aborted and the whole
@@ -165,7 +158,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         """
         raise ValueError
 
-    def add_target_and_index(self, name: T, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -207,8 +200,46 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         for i in range(1, num+1):
             ls.append((rst_file, start_num+i))
         return ls
+    
+    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
+        """
+        Returns a tuple of strings, one entry for each part of the object's
+        hierarchy (e.g. ``('module', 'submodule', 'Class', 'method')``). The
+        returned tuple is used to properly nest children within parents in the
+        table of contents, and can also be used within the
+        :py:meth:`_toc_entry_name` method.
+
+        This method must not be used outwith table of contents generation.
+        """
+        return ()
+
+    def _toc_entry_name(self, sig_node: desc_signature) -> str:
+        """
+        Returns the text of the table of contents entry for the object.
+
+        This function is called once, in :py:meth:`run`, to set the name for the
+        table of contents entry (a special attribute ``_toc_name`` is set on the
+        object node, later used in
+        ``environment.collectors.toctree.TocTreeCollector.process_doc().build_toc()``
+        when the table of contents entries are collected).
+
+        To support table of contents entries for their objects, domains must
+        override this method, also respecting the configuration setting
+        ``toc_object_entries_show_parents``. Domains must also override
+        :py:meth:`_object_hierarchy_parts`, with one (string) entry for each part of the
+        object's hierarchy. The result of this method is set on the signature
+        node, and can be accessed as ``sig_node['_toc_parts']`` for use within
+        this method. The resulting tuple is also used to properly nest children
+        within parents in the table of contents.
+
+        An example implementations of this method is within the python domain
+        (:meth:`!PyObject._toc_entry_name`). The python domain sets the
+        ``_toc_parts`` attribute within the :py:meth:`handle_signature()`
+        method.
+        """
+        return ''
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         """
         Main directive entry function, called by docutils upon encountering the
         directive.
@@ -234,15 +265,28 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         node = addnodes.desc()
         node.document = self.state.document
+        source, line = self.get_source_info()
+        # If any options were specified to the directive,
+        # self.state.document.current_line will at this point be set to
+        # None.  To ensure nodes created as part of the signature have a line
+        # number set, set the document's line number correctly.
+        #
+        # Note that we need to subtract one from the line number since
+        # note_source uses 0-based line numbers.
+        if line is not None:
+            line -= 1
+        self.state.document.note_source(source, line)
         node['domain'] = self.domain
         # 'desctype' is a backwards compatible attribute
         node['objtype'] = node['desctype'] = self.objtype
         node['noindex'] = noindex = ('noindex' in self.options)
+        node['noindexentry'] = ('noindexentry' in self.options)
+        node['nocontentsentry'] = ('nocontentsentry' in self.options)
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
 
-        self.names: List[T] = []
+        self.names: list[ObjDescT] = []
         signatures = self.get_signatures()
         for sig in signatures:
             # add a signature node for each signature in the current unit
@@ -260,6 +304,15 @@ class ObjectDescription(SphinxDirective, Generic[T]):
                 signode.clear()
                 signode += addnodes.desc_name(sig, sig)
                 continue  # we don't want an index entry here
+            finally:
+                # Private attributes for ToC generation. Will be modified or removed
+                # without notice.
+                if self.env.app.config.toc_object_entries:
+                    signode['_toc_parts'] = self._object_hierarchy_parts(signode)
+                    signode['_toc_name'] = self._toc_entry_name(signode)
+                else:
+                    signode['_toc_parts'] = ()
+                    signode['_toc_name'] = ''
             if name not in self.names:
                 self.names.append(name)
                 if not noindex:
@@ -269,6 +322,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
 
         contentnode = addnodes.desc_content()
         node.append(contentnode)
+
         if self.names:
             # needed for association of version{added,changed} directives
             self.env.temp_data['object'] = self.names[0]
@@ -302,7 +356,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
             self.content.items.extend(self.extend_items(self.content.items[0][0], self.content.items[-1][1], len(extra)))
         except IndexError:
             logger.warning(f'{self.names[0][0]} has error format.')
-        self.state.nested_parse(self.content, self.content_offset, contentnode)
+        nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
         self.transform_content(contentnode)
         self.env.app.emit('object-description-transform',
                           self.domain, self.objtype, contentnode)
@@ -320,14 +374,14 @@ class DefaultRole(SphinxDirective):
     optional_arguments = 1
     final_argument_whitespace = False
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         if not self.arguments:
             docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
         role, messages = roles.role(role_name, self.state_machine.language,
                                     self.lineno, self.state.reporter)
-        if role:
+        if role:  # type: ignore[truthy-function]
             docutils.register_role('', role)
             self.env.temp_data['default_role'] = role_name
         else:
@@ -351,7 +405,7 @@ class DefaultDomain(SphinxDirective):
     final_argument_whitespace = False
     option_spec: OptionSpec = {}
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()
         # if domain_name not in env.domains:
         #     # try searching by label
@@ -363,10 +417,7 @@ class DefaultDomain(SphinxDirective):
         return []
 
 
-
-
-
-def setup(app: "Sphinx") -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value("strip_signature_backslash", False, 'env')
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)
diff --git a/docs/mindquantum/docs/_ext/overwriteviewcode.txt b/docs/mindquantum/docs/_ext/overwriteviewcode.txt
index 172780ec56b3ed90e7b0add617257a618cf38ee0..a2fdcfb787bb99e6d96742574675f79151a4848d 100644
--- a/docs/mindquantum/docs/_ext/overwriteviewcode.txt
+++ b/docs/mindquantum/docs/_ext/overwriteviewcode.txt
@@ -1,18 +1,12 @@
-"""
-    sphinx.ext.viewcode
-    ~~~~~~~~~~~~~~~~~~~
+"""Add links to module code in Python object descriptions."""
 
-    Add links to module code in Python object descriptions.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import posixpath
 import traceback
 import warnings
 from os import path
-from typing import Any, Dict, Generator, Iterable, Optional, Set, Tuple, cast
+from typing import Any, Generator, Iterable, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
@@ -22,12 +16,12 @@ from sphinx import addnodes
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import get_full_modname, logging, status_iterator
+from sphinx.util import get_full_modname, logging
+from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
 
 
@@ -46,13 +40,13 @@ class viewcode_anchor(Element):
     """
 
 
-def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str]:
+def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> str | None:
     try:
         return get_full_modname(modname, attribute)
     except AttributeError:
         # sphinx.ext.viewcode can't follow class instance attribute
         # then AttributeError logging output only verbose mode.
-        logger.verbose('Didn\'t find %s in %s', attribute, modname)
+        logger.verbose("Didn't find %s in %s", attribute, modname)
         return None
     except Exception as e:
         # sphinx.ext.viewcode follow python domain directives.
@@ -67,12 +61,11 @@ def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str
 def is_supported_builder(builder: Builder) -> bool:
     if builder.format != 'html':
         return False
-    elif builder.name == 'singlehtml':
+    if builder.name == 'singlehtml':
         return False
-    elif builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
+    if builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
         return False
-    else:
-        return True
+    return True
 
 
 def doctree_read(app: Sphinx, doctree: Node) -> None:
@@ -112,7 +105,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
     for objnode in list(doctree.findall(addnodes.desc)):
         if objnode.get('domain') != 'py':
             continue
-        names: Set[str] = set()
+        names: set[str] = set()
         for signode in objnode:
             if not isinstance(signode, addnodes.desc_signature):
                 continue
@@ -211,19 +204,7 @@ class ViewcodeAnchorTransform(SphinxPostTransform):
             node.parent.remove(node)
 
 
-def missing_reference(app: Sphinx, env: BuildEnvironment, node: Element, contnode: Node
-                      ) -> Optional[Node]:
-    # resolve our "viewcode" reference nodes -- they need special treatment
-    if node['reftype'] == 'viewcode':
-        warnings.warn('viewcode extension is no longer use pending_xref node. '
-                      'Please update your extension.', RemovedInSphinx50Warning)
-        return make_refnode(app.builder, node['refdoc'], node['reftarget'],
-                            node['refid'], contnode)
-
-    return None
-
-
-def get_module_filename(app: Sphinx, modname: str) -> Optional[str]:
+def get_module_filename(app: Sphinx, modname: str) -> str | None:
     """Get module filename for *modname*."""
     source_info = app.emit_firstresult('viewcode-find-source', modname)
     if source_info:
@@ -251,13 +232,13 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
         if path.getmtime(module_filename) <= path.getmtime(page_filename):
             # generation is not needed if the HTML page is newer than module file.
             return False
-    except IOError:
+    except OSError:
         pass
 
     return True
 
 
-def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], None, None]:
+def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], None, None]:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
         return
@@ -282,7 +263,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
         # construct a page name for the highlighted source
         pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))
         # highlight the source using the builder's highlighter
-        if env.config.highlight_language in ('python3', 'default', 'none'):
+        if env.config.highlight_language in {'default', 'none'}:
             lexer = env.config.highlight_language
         else:
             lexer = 'python'
@@ -343,10 +324,9 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
                 stack.pop()
                 html.append('</ul>')
             stack.append(modname + '.')
-        html.append('<li><a href="%s">%s</a></li>\n' % (
-            urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
-                  posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))),
-            modname))
+        relative_uri = urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
+                             posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/')))
+        html.append(f'<li><a href="{relative_uri}">{modname}</a></li>\n')
     html.append('</ul>' * (len(stack) - 1))
     context = {
         'title': _('Overview: module code'),
@@ -357,7 +337,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
     yield (posixpath.join(OUTPUT_DIRNAME, 'index'), context, 'page.html')
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('viewcode_import', None, False)
     app.add_config_value('viewcode_enable_epub', False, False)
     app.add_config_value('viewcode_follow_imported_members', True, False)
@@ -365,7 +345,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect('env-merge-info', env_merge_info)
     app.connect('env-purge-doc', env_purge_doc)
     app.connect('html-collect-pages', collect_pages)
-    app.connect('missing-reference', missing_reference)
     # app.add_config_value('viewcode_include_modules', [], 'env')
     # app.add_config_value('viewcode_exclude_modules', [], 'env')
     app.add_event('viewcode-find-source')
@@ -374,5 +353,5 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     return {
         'version': sphinx.__display_version__,
         'env_version': 1,
-        'parallel_read_safe': True
+        'parallel_read_safe': True,
     }
diff --git a/docs/mindquantum/docs/requirements.txt b/docs/mindquantum/docs/requirements.txt
index 3d9921cabc71a58c8fb11c0d6f72796e9af7a7ba..d01e7ccb0deb0f123ff721825510db0e0fd1e596 100644
--- a/docs/mindquantum/docs/requirements.txt
+++ b/docs/mindquantum/docs/requirements.txt
@@ -1,6 +1,6 @@
-sphinx == 4.4.0
-docutils == 0.17.1
-myst-parser == 0.18.1
-sphinx_rtd_theme == 1.0.0
+sphinx == 7.0.1
+docutils == 0.20.1
+myst-parser == 2.0.0
+sphinx_rtd_theme == 3.0.0
 jieba
 numpy
diff --git a/docs/mindspore/_ext/customdocumenter.txt b/docs/mindspore/_ext/customdocumenter.txt
index 2d37ae41f6772a21da2a7dc5c7bff75128e68330..505ed7c57e6d7a30d106ca7a33111df6a8278ad3 100644
--- a/docs/mindspore/_ext/customdocumenter.txt
+++ b/docs/mindspore/_ext/customdocumenter.txt
@@ -8,7 +8,7 @@ class CustomDocumenter(Documenter):
     def document_members(self, all_members: bool = False) -> None:
         """Generate reST for member documentation.
 
-        If *all_members* is True, do all members, else those given by
+        If *all_members* is True, document all members, else those given by
         *self.options.members*.
         """
         # set current namespace for finding members
@@ -16,8 +16,9 @@ class CustomDocumenter(Documenter):
         if self.objpath:
             self.env.temp_data['autodoc:class'] = self.objpath[0]
 
-        want_all = all_members or self.options.inherited_members or \
-            self.options.members is ALL
+        want_all = (all_members or
+                    self.options.inherited_members or
+                    self.options.members is ALL)
         # find out which members are documentable
         members_check_module, members = self.get_object_members(want_all)
 
@@ -59,7 +60,7 @@ class CustomDocumenter(Documenter):
             ]
 
         # document non-skipped members
-        memberdocumenters = []  # type: List[Tuple[Documenter, bool]]
+        memberdocumenters: list[tuple[Documenter, bool]] = []
         for (mname, member, isattr) in self.filter_members(members, want_all):
             classes = [cls for cls in self.documenters.values()
                        if cls.can_document_member(member, mname, isattr, self)]
@@ -111,7 +112,7 @@ class CustomDocumenter(Documenter):
         if not self.parse_name():
             # need a module to import
             logger.warning(
-                __('don\'t know which module to import for autodocumenting '
+                __("don't know which module to import for autodocumenting "
                    '%r (try placing a "module" or "currentmodule" directive '
                    'in the document, or giving an explicit module name)') %
                 self.name, type='autodoc')
@@ -126,7 +127,8 @@ class CustomDocumenter(Documenter):
         # where the attribute documentation would actually be found in.
         # This is used for situations where you have a module that collects the
         # functions and classes of internal submodules.
-        self.real_modname = real_modname or self.get_real_modname()  # type: str
+        guess_modname = self.get_real_modname()
+        self.real_modname: str = real_modname or guess_modname
 
         # try to also get a source code analyzer for attribute docs
         try:
@@ -134,15 +136,28 @@ class CustomDocumenter(Documenter):
             # parse right now, to get PycodeErrors on parsing (results will
             # be cached anyway)
             self.analyzer.find_attr_docs()
-        except PycodeError as err:
-            logger.debug('[autodoc] module analyzer failed: %s', err)
+        except PycodeError as exc:
+            logger.debug('[autodoc] module analyzer failed: %s', exc)
             # no source file -- e.g. for builtin and C modules
             self.analyzer = None
             # at least add the module.__file__ as a dependency
             if hasattr(self.module, '__file__') and self.module.__file__:
-                self.directive.filename_set.add(self.module.__file__)
+                self.directive.record_dependencies.add(self.module.__file__)
         else:
-            self.directive.filename_set.add(self.analyzer.srcname)
+            self.directive.record_dependencies.add(self.analyzer.srcname)
+
+        if self.real_modname != guess_modname:
+            # Add module to dependency list if target object is defined in other module.
+            try:
+                analyzer = ModuleAnalyzer.for_module(guess_modname)
+                self.directive.record_dependencies.add(analyzer.srcname)
+            except PycodeError:
+                pass
+
+        docstrings: list[str] = sum(self.get_doc() or [], [])
+        if ismock(self.object) and not docstrings:
+            logger.warning(__('A mocked object is detected: %r'),
+                           self.name, type='autodoc')
 
         # check __module__ of object (for members not given explicitly)
         if check_module:
@@ -160,29 +175,41 @@ class ModuleDocumenter(CustomDocumenter):
     objtype = 'module'
     content_indent = ''
     titles_allowed = True
+    _extra_indent = '   '
 
-    option_spec = {
+    option_spec: OptionSpec = {
         'members': members_option, 'undoc-members': bool_option,
-        'noindex': bool_option, 'inherited-members': bool_option,
+        'noindex': bool_option, 'inherited-members': inherited_members_option,
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
-        'member-order': identity, 'exclude-members': members_set_option,
-        'private-members': bool_option, 'special-members': members_option,
-        'imported-members': bool_option, 'ignore-module-all': bool_option
-    }  # type: Dict[str, Callable]
+        'member-order': member_order_option, 'exclude-members': exclude_members_option,
+        'private-members': members_option, 'special-members': members_option,
+        'imported-members': bool_option, 'ignore-module-all': bool_option,
+        'no-value': bool_option,
+    }
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
         merge_members_option(self.options)
+        self.__all__: Sequence[str] | None = None
+
+    def add_content(self, more_content: StringList | None) -> None:
+        old_indent = self.indent
+        self.indent += self._extra_indent
+        super().add_content(None)
+        self.indent = old_indent
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         # don't document submodules automatically
         return False
 
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         if modname is not None:
             logger.warning(__('"::" in automodule name doesn\'t make sense'),
                            type='autodoc')
@@ -196,6 +223,20 @@ class ModuleDocumenter(CustomDocumenter):
                            type='autodoc')
         return ret
 
+    def import_object(self, raiseerror: bool = False) -> bool:
+        ret = super().import_object(raiseerror)
+
+        try:
+            if not self.options.ignore_module_all:
+                self.__all__ = inspect.getall(self.object)
+        except ValueError as exc:
+            # invalid __all__ found.
+            logger.warning(__('__all__ should be a list of strings, not %r '
+                              '(in module %s) -- ignoring __all__') %
+                           (exc.args[0], self.fullname), type='autodoc')
+
+        return ret
+
     def add_directive_header(self, sig: str) -> None:
         Documenter.add_directive_header(self, sig)
 
@@ -209,37 +250,57 @@ class ModuleDocumenter(CustomDocumenter):
         if self.options.deprecated:
             self.add_line('   :deprecated:', sourcename)
 
-    def get_object_members(self, want_all: bool) -> Tuple[bool, List[Tuple[str, object]]]:
+    def get_module_members(self) -> dict[str, ObjectMember]:
+        """Get members of target module."""
+        if self.analyzer:
+            attr_docs = self.analyzer.attr_docs
+        else:
+            attr_docs = {}
+
+        members: dict[str, ObjectMember] = {}
+        for name in dir(self.object):
+            try:
+                value = safe_getattr(self.object, name, None)
+                if ismock(value):
+                    value = undecorate(value)
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, value, docstring="\n".join(docstring))
+            except AttributeError:
+                continue
+
+        # annotation only member (ex. attr: int)
+        for name in inspect.getannotations(self.object):
+            if name not in members:
+                docstring = attr_docs.get(('', name), [])
+                members[name] = ObjectMember(name, INSTANCEATTR,
+                                             docstring="\n".join(docstring))
+
+        return members
+
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        members = self.get_module_members()
         if want_all:
             if (self.options.ignore_module_all or not
                     hasattr(self.object, '__all__')):
                 # for implicit module members, check __module__ to avoid
                 # documenting imported objects
-                return True, get_module_members(self.object)
+                return True, list(members.values())
             else:
-                memberlist = self.object.__all__
-                # Sometimes __all__ is broken...
-                if not isinstance(memberlist, (list, tuple)) or not \
-                   all(isinstance(entry, str) for entry in memberlist):
-                    logger.warning(
-                        __('__all__ should be a list of strings, not %r '
-                           '(in module %s) -- ignoring __all__') %
-                        (memberlist, self.fullname),
-                        type='autodoc'
-                    )
-                    # fall back to all members
-                    return True, get_module_members(self.object)
+                for member in members.values():
+                    if member.__name__ not in self.__all__:
+                        member.skipped = True
+
+                # fall back to all members
+                return True,  list(members.values())
         else:
             memberlist = self.options.members or []
-        ret = []
-        for mname in memberlist:
-            try:
-                ret.append((mname, safe_getattr(self.object, mname)))
-            except AttributeError:
-                logger.warning(
-                    __('missing attribute mentioned in :members: or __all__: '
-                       'module %s, attribute %s') %
-                    (safe_getattr(self.object, '__name__', '???'), mname),
-                    type='autodoc'
-                )
-        return False, ret
+            ret = []
+            for name in memberlist:
+                if name in members:
+                    ret.append(members[name])
+                else:
+                    logger.warning(__('missing attribute mentioned in :members: option: '
+                                      'module %s, attribute %s') %
+                                   (safe_getattr(self.object, '__name__', '???'), name),
+                                   type='autodoc')
+            return False, ret
diff --git a/docs/mindspore/_ext/overwrite_autodoc.txt b/docs/mindspore/_ext/overwrite_autodoc.txt
index 58aaf9d028fd7e27382ba02b09be3eec95c8bedc..b6f86c240db5d154251e82249183d9d04f7a5624 100644
--- a/docs/mindspore/_ext/overwrite_autodoc.txt
+++ b/docs/mindspore/_ext/overwrite_autodoc.txt
@@ -1,44 +1,52 @@
-"""
-    sphinx.ext.autodoc
-    ~~~~~~~~~~~~~~~~~~
-
-    Automatically insert docstrings for functions, classes or whole modules into
-    the doctree, thus avoiding duplication between docstrings and documentation
-    for those who like elaborate docstrings.
+"""Extension to create automatic documentation from code docstrings.
 
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+Automatically insert docstrings for functions, classes or whole modules into
+the doctree, thus avoiding duplication between docstrings and documentation
+for those who like elaborate docstrings.
 """
 
+from __future__ import annotations
+
 import re
-import warnings
+import sys
 from inspect import Parameter, Signature
-from types import ModuleType
-from typing import (TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional, Sequence,
-                    Set, Tuple, Type, TypeVar, Union)
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Iterator,
+    List,
+    Sequence,
+    Tuple,
+    TypeVar,
+    Union,
+)
 
 from docutils.statemachine import StringList
 
 import sphinx
 from sphinx.application import Sphinx
 from sphinx.config import ENUM, Config
-from sphinx.deprecation import RemovedInSphinx50Warning, RemovedInSphinx60Warning
 from sphinx.environment import BuildEnvironment
-from sphinx.ext.autodoc.importer import (get_class_members, get_object_members, import_module,
-                                         import_object)
+from sphinx.ext.autodoc.importer import get_class_members, import_module, import_object
 from sphinx.ext.autodoc.mock import ismock, mock, undecorate
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.util import inspect, logging, get_full_modname
 from sphinx.util.docstrings import prepare_docstring, separate_metadata
-from sphinx.util.inspect import (evaluate_signature, getdoc, object_description, safe_getattr,
-                                 stringify_signature)
-from sphinx.util.typing import OptionSpec, get_type_hints, restify
-from sphinx.util.typing import stringify as stringify_typehint
+from sphinx.util.inspect import (
+    evaluate_signature,
+    getdoc,
+    object_description,
+    safe_getattr,
+    stringify_signature,
+)
+from sphinx.util.typing import OptionSpec, get_type_hints, restify, stringify_annotation
 
 if TYPE_CHECKING:
-    from sphinx.ext.autodoc.directive import DocumenterBridge
+    from types import ModuleType
 
+    from sphinx.ext.autodoc.directive import DocumenterBridge
 
 logger = logging.getLogger(__name__)
 
@@ -88,7 +96,7 @@ INSTANCEATTR = object()
 SLOTSATTR = object()
 
 
-def members_option(arg: Any) -> Union[object, List[str]]:
+def members_option(arg: Any) -> object | list[str]:
     """Used to convert the :members: option to auto directives."""
     if arg in (None, True):
         return ALL
@@ -98,32 +106,25 @@ def members_option(arg: Any) -> Union[object, List[str]]:
         return [x.strip() for x in arg.split(',') if x.strip()]
 
 
-def members_set_option(arg: Any) -> Union[object, Set[str]]:
-    """Used to convert the :members: option to auto directives."""
-    warnings.warn("members_set_option() is deprecated.",
-                  RemovedInSphinx50Warning, stacklevel=2)
-    if arg is None:
-        return ALL
-    return {x.strip() for x in arg.split(',') if x.strip()}
-
-
-def exclude_members_option(arg: Any) -> Union[object, Set[str]]:
+def exclude_members_option(arg: Any) -> object | set[str]:
     """Used to convert the :exclude-members: option."""
     if arg in (None, True):
         return EMPTY
     return {x.strip() for x in arg.split(',') if x.strip()}
 
 
-def inherited_members_option(arg: Any) -> Union[object, Set[str]]:
-    """Used to convert the :members: option to auto directives."""
+def inherited_members_option(arg: Any) -> set[str]:
+    """Used to convert the :inherited-members: option to auto directives."""
     if arg in (None, True):
-        return 'object'
+        return {'object'}
+    elif arg:
+        return {x.strip() for x in arg.split(',')}
     else:
-        return arg
+        return set()
 
 
-def member_order_option(arg: Any) -> Optional[str]:
-    """Used to convert the :members: option to auto directives."""
+def member_order_option(arg: Any) -> str | None:
+    """Used to convert the :member-order: option to auto directives."""
     if arg in (None, True):
         return None
     elif arg in ('alphabetical', 'bysource', 'groupwise'):
@@ -132,7 +133,7 @@ def member_order_option(arg: Any) -> Optional[str]:
         raise ValueError(__('invalid value for member-order option: %s') % arg)
 
 
-def class_doc_from_option(arg: Any) -> Optional[str]:
+def class_doc_from_option(arg: Any) -> str | None:
     """Used to convert the :class-doc-from: option to autoclass directives."""
     if arg in ('both', 'class', 'init'):
         return arg
@@ -158,23 +159,10 @@ def bool_option(arg: Any) -> bool:
     return True
 
 
-def merge_special_members_option(options: Dict) -> None:
-    """Merge :special-members: option to :members: option."""
-    warnings.warn("merge_special_members_option() is deprecated.",
-                  RemovedInSphinx50Warning, stacklevel=2)
-    if 'special-members' in options and options['special-members'] is not ALL:
-        if options.get('members') is ALL:
-            pass
-        elif options.get('members'):
-            for member in options['special-members']:
-                if member not in options['members']:
-                    options['members'].append(member)
-        else:
-            options['members'] = options['special-members']
-
-
-def merge_members_option(options: Dict) -> None:
-    """Merge :*-members: option to the :members: option."""
+def merge_members_option(options: dict) -> None:
+    """Merge :private-members: and :special-members: options to the
+    :members: option.
+    """
     if options.get('members') is ALL:
         # merging is not needed when members: ALL
         return
@@ -189,7 +177,7 @@ def merge_members_option(options: Dict) -> None:
 
 # Some useful event listener factories for autodoc-process-docstring.
 
-def cut_lines(pre: int, post: int = 0, what: str = None) -> Callable:
+def cut_lines(pre: int, post: int = 0, what: str | None = None) -> Callable:
     """Return a listener that removes the first *pre* and last *post*
     lines of every docstring.  If *what* is a sequence of strings,
     only docstrings of a type in *what* will be processed.
@@ -201,7 +189,7 @@ def cut_lines(pre: int, post: int = 0, what: str = None) -> Callable:
 
     This can (and should) be used in place of :confval:`automodule_skip_lines`.
     """
-    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: List[str]
+    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str],
                 ) -> None:
         if what and what_ not in what:
             return
@@ -217,8 +205,12 @@ def cut_lines(pre: int, post: int = 0, what: str = None) -> Callable:
     return process
 
 
-def between(marker: str, what: Sequence[str] = None, keepempty: bool = False,
-            exclude: bool = False) -> Callable:
+def between(
+    marker: str,
+    what: Sequence[str] | None = None,
+    keepempty: bool = False,
+    exclude: bool = False,
+) -> Callable:
     """Return a listener that either keeps, or if *exclude* is True excludes,
     lines between lines that match the *marker* regular expression.  If no line
     matches, the resulting docstring would be empty, so no change will be made
@@ -229,7 +221,7 @@ def between(marker: str, what: Sequence[str] = None, keepempty: bool = False,
     """
     marker_re = re.compile(marker)
 
-    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: List[str]
+    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str],
                 ) -> None:
         if what and what_ not in what:
             return
@@ -257,7 +249,7 @@ def between(marker: str, what: Sequence[str] = None, keepempty: bool = False,
 # But we define this class here to keep compatibility (see #4538)
 class Options(dict):
     """A dict/attribute hybrid that returns None on nonexisting keys."""
-    def copy(self) -> "Options":
+    def copy(self) -> Options:
         return Options(super().copy())
 
     def __getattr__(self, name: str) -> Any:
@@ -270,7 +262,7 @@ class Options(dict):
 class ObjectMember(tuple):
     """A member of object.
 
-    This is used for the result of `Documenter.get_object_members()` to
+    This is used for the result of `Documenter.get_module_members()` to
     represent each member of the object.
 
     .. Note::
@@ -284,7 +276,7 @@ class ObjectMember(tuple):
     def __new__(cls, name: str, obj: Any, **kwargs: Any) -> Any:
         return super().__new__(cls, (name, obj))  # type: ignore
 
-    def __init__(self, name: str, obj: Any, docstring: Optional[str] = None,
+    def __init__(self, name: str, obj: Any, docstring: str | None = None,
                  class_: Any = None, skipped: bool = False) -> None:
         self.__name__ = name
         self.object = obj
@@ -321,10 +313,10 @@ class Documenter:
     #: order if autodoc_member_order is set to 'groupwise'
     member_order = 0
     #: true if the generated content may contain titles
-    titles_allowed = False
+    titles_allowed = True
 
     option_spec: OptionSpec = {
-        'noindex': bool_option
+        'noindex': bool_option,
     }
 
     def get_attr(self, obj: Any, name: str, *defargs: Any) -> Any:
@@ -332,12 +324,12 @@ class Documenter:
         return autodoc_attrgetter(self.env.app, obj, name, *defargs)
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         """Called to see if a member can be documented by this Documenter."""
         raise NotImplementedError('must be implemented in subclasses')
 
-    def __init__(self, directive: "DocumenterBridge", name: str, indent: str = '') -> None:
+    def __init__(self, directive: DocumenterBridge, name: str, indent: str = '') -> None:
         self.directive = directive
         self.config: Config = directive.env.config
         self.env: BuildEnvironment = directive.env
@@ -348,7 +340,7 @@ class Documenter:
         # qualified name (all set after resolve_name succeeds)
         self.modname: str = None
         self.module: ModuleType = None
-        self.objpath: List[str] = None
+        self.objpath: list[str] = None
         self.fullname: str = None
         # extra signature items (arguments and return annotation,
         # also set after resolve_name succeeds)
@@ -363,7 +355,7 @@ class Documenter:
         self.analyzer: ModuleAnalyzer = None
 
     @property
-    def documenters(self) -> Dict[str, Type["Documenter"]]:
+    def documenters(self) -> dict[str, type[Documenter]]:
         """Returns registered Documenter classes"""
         return self.env.app.registry.documenters
 
@@ -374,8 +366,8 @@ class Documenter:
         else:
             self.directive.result.append('', source, *lineno)
 
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         """Resolve the module and name of the object to document given by the
         arguments and the current module/class.
 
@@ -440,10 +432,9 @@ class Documenter:
             except ImportError as exc:
                 if raiseerror:
                     raise
-                else:
-                    logger.warning(exc.args[0], type='autodoc', subtype='import_object')
-                    self.env.note_reread()
-                    return False
+                logger.warning(exc.args[0], type='autodoc', subtype='import_object')
+                self.env.note_reread()
+                return False
 
     def get_real_modname(self) -> str:
         """Get the real module name of an object to document.
@@ -466,12 +457,12 @@ class Documenter:
             return False
         return True
 
-    def format_args(self, **kwargs: Any) -> str:
+    def format_args(self, **kwargs: Any) -> str | None:
         """Format the argument signature of *self.object*.
 
         Should return None if the object does not have a signature.
         """
-        return None
+        pass
 
     def format_name(self) -> str:
         """Format the name of *self.object*.
@@ -484,7 +475,7 @@ class Documenter:
         # directives of course)
         return '.'.join(self.objpath) or self.modname
 
-    def _call_format_args(self, **kwargs: Any) -> str:
+    def _call_format_args(self, **kwargs: Any) -> str | None:
         if kwargs:
             try:
                 return self.format_args(**kwargs)
@@ -538,9 +529,9 @@ class Documenter:
         sourcename = self.get_sourcename()
 
         # one signature per line, indented by column
-        prefix = '.. %s:%s:: ' % (domain, directive)
+        prefix = f'.. {domain}:{directive}:: '
         for i, sig_line in enumerate(sig.split("\n")):
-            self.add_line('%s%s%s' % (prefix, name, sig_line),
+            self.add_line(f'{prefix}{name}{sig_line}',
                           sourcename)
             if i == 0:
                 prefix = " " * len(prefix)
@@ -552,16 +543,12 @@ class Documenter:
             # etc. don't support a prepended module name
             self.add_line('   :module: %s' % self.modname, sourcename)
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
         """Decode and return lines of the docstring(s) for the object.
 
         When it returns None, autodoc-process-docstring will not be called for this
         object.
         """
-        if ignore is not None:
-            warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated."
-                          % self.__class__.__name__,
-                          RemovedInSphinx50Warning, stacklevel=2)
         docstring = getdoc(self.object, self.get_attr, self.config.autodoc_inherit_docstrings,
                            self.parent, self.object_name)
         spec_tp = [('ops.dense', 'ops.linear'), ('ops.inverse_ext', ['mint.linalg.inv', 'mint.inverse'])]
@@ -590,10 +577,10 @@ class Documenter:
 
         if docstring:
             tab_width = self.directive.state.document.settings.tab_width
-            return [prepare_docstring(docstring, ignore, tab_width)]
+            return [prepare_docstring(docstring, tab_width)]
         return []
 
-    def process_doc(self, docstrings: List[List[str]]) -> Iterator[str]:
+    def process_doc(self, docstrings: list[list[str]]) -> Iterator[str]:
         """Let the user process the docstrings before adding them."""
         for docstringlines in docstrings:
             if self.env.app:
@@ -613,22 +600,18 @@ class Documenter:
                 inspect.safe_getattr(self.object, '__qualname__', None)):
             # Get the correct location of docstring from self.object
             # to support inherited methods
-            fullname = '%s.%s' % (self.object.__module__, self.object.__qualname__)
+            fullname = f'{self.object.__module__}.{self.object.__qualname__}'
         else:
             fullname = self.fullname
 
         if self.analyzer:
-            return '%s:docstring of %s' % (self.analyzer.srcname, fullname)
+            return f'{self.analyzer.srcname}:docstring of {fullname}'
         else:
             return 'docstring of %s' % fullname
 
-    def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
-                    ) -> None:
+    def add_content(self, more_content: StringList | None) -> None:
         """Add content from docstrings, attribute documentation and user."""
-        if no_docstring:
-            warnings.warn("The 'no_docstring' argument to %s.add_content() is deprecated."
-                          % self.__class__.__name__,
-                          RemovedInSphinx50Warning, stacklevel=2)
+        docstring = True
 
         # set sourcename and add content from attribute documentation
         sourcename = self.get_sourcename()
@@ -637,7 +620,7 @@ class Documenter:
             if self.objpath:
                 key = ('.'.join(self.objpath[:-1]), self.objpath[-1])
                 if key in attr_docs:
-                    no_docstring = True
+                    docstring = False
                     # make a copy of docstring for attributes to avoid cache
                     # the change of autodoc-process-docstring event.
                     docstrings = [list(attr_docs[key])]
@@ -646,7 +629,7 @@ class Documenter:
                         self.add_line(line, sourcename, i)
 
         # add content from docstrings
-        if not no_docstring:
+        if docstring:
             docstrings = self.get_doc()
             if docstrings is None:
                 # Do not call autodoc-process-docstring on get_doc() returns None.
@@ -665,36 +648,17 @@ class Documenter:
             for line, src in zip(more_content.data, more_content.items):
                 self.add_line(line, src[0], src[1])
 
-    def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
         """Return `(members_check_module, members)` where `members` is a
         list of `(membername, member)` pairs of the members of *self.object*.
 
         If *want_all* is True, return all members.  Else, only return those
         members given by *self.options.members* (which may also be None).
         """
-        warnings.warn('The implementation of Documenter.get_object_members() will be '
-                      'removed from Sphinx-6.0.', RemovedInSphinx60Warning)
-        members = get_object_members(self.object, self.objpath, self.get_attr, self.analyzer)
-        if not want_all:
-            if not self.options.members:
-                return False, []  # type: ignore
-            # specific members given
-            selected = []
-            for name in self.options.members:  # type: str
-                if name in members:
-                    selected.append((name, members[name].value))
-                else:
-                    logger.warning(__('missing attribute %s in object %s') %
-                                   (name, self.fullname), type='autodoc')
-            return False, selected
-        elif self.options.inherited_members:
-            return False, [(m.name, m.value) for m in members.values()]
-        else:
-            return False, [(m.name, m.value) for m in members.values()
-                           if m.directly_defined]
+        raise NotImplementedError('must be implemented in subclasses')
 
-    def filter_members(self, members: ObjectMembers, want_all: bool
-                       ) -> List[Tuple[str, Any, bool]]:
+    def filter_members(self, members: ObjectMembers, want_all: bool,
+                       ) -> list[tuple[str, Any, bool]]:
         """Filter the given member list.
 
         Members are skipped if
@@ -709,16 +673,18 @@ class Documenter:
         ``autodoc-skip-member`` event.
         """
         def is_filtered_inherited_member(name: str, obj: Any) -> bool:
+            inherited_members = self.options.inherited_members or set()
+
             if inspect.isclass(self.object):
                 for cls in self.object.__mro__:
-                    if cls.__name__ == self.options.inherited_members and cls != self.object:
+                    if cls.__name__ in inherited_members and cls != self.object:
                         # given member is a member of specified *super class*
                         return True
-                    elif name in cls.__dict__:
+                    if name in cls.__dict__:
                         return False
-                    elif name in self.get_attr(cls, '__annotations__', {}):
+                    if name in self.get_attr(cls, '__annotations__', {}):
                         return False
-                    elif isinstance(obj, ObjectMember) and obj.class_ is cls:
+                    if isinstance(obj, ObjectMember) and obj.class_ is cls:
                         return False
 
             return False
@@ -738,12 +704,7 @@ class Documenter:
             try:
                 membername, member = obj
                 # if isattr is True, the member is documented as an attribute
-                if member is INSTANCEATTR:
-                    isattr = True
-                elif (namespace, membername) in attr_docs:
-                    isattr = True
-                else:
-                    isattr = False
+                isattr = member is INSTANCEATTR or (namespace, membername) in attr_docs
 
                 doc = getdoc(member, self.get_attr, self.config.autodoc_inherit_docstrings,
                              self.object, membername)
@@ -787,7 +748,7 @@ class Documenter:
                     # special __methods__
                     if (self.options.special_members and
                             membername in self.options.special_members):
-                        if membername == '__doc__':
+                        if membername == '__doc__':  # NoQA: SIM114
                             keep = False
                         elif is_filtered_inherited_member(membername, obj):
                             keep = False
@@ -806,7 +767,7 @@ class Documenter:
                         keep = True
                 elif want_all and isprivate:
                     if has_doc or self.options.undoc_members:
-                        if self.options.private_members is None:
+                        if self.options.private_members is None:  # NoQA: SIM114
                             keep = False
                         elif is_filtered_inherited_member(membername, obj):
                             keep = False
@@ -864,7 +825,7 @@ class Documenter:
         members_check_module, members = self.get_object_members(want_all)
 
         # document non-skipped members
-        memberdocumenters: List[Tuple[Documenter, bool]] = []
+        memberdocumenters: list[tuple[Documenter, bool]] = []
         for (mname, member, isattr) in self.filter_members(members, want_all):
             classes = [cls for cls in self.documenters.values()
                        if cls.can_document_member(member, mname, isattr, self)]
@@ -891,33 +852,35 @@ class Documenter:
         self.env.temp_data['autodoc:module'] = None
         self.env.temp_data['autodoc:class'] = None
 
-    def sort_members(self, documenters: List[Tuple["Documenter", bool]],
-                     order: str) -> List[Tuple["Documenter", bool]]:
+    def sort_members(self, documenters: list[tuple[Documenter, bool]],
+                     order: str) -> list[tuple[Documenter, bool]]:
         """Sort the given member list."""
         if order == 'groupwise':
             # sort by group; alphabetically within groups
             documenters.sort(key=lambda e: (e[0].member_order, e[0].name))
         elif order == 'bysource':
+            # By default, member discovery order matches source order,
+            # as dicts are insertion-ordered from Python 3.7.
             if self.analyzer:
                 # sort by source order, by virtue of the module analyzer
                 tagorder = self.analyzer.tagorder
 
-                def keyfunc(entry: Tuple[Documenter, bool]) -> int:
+                def keyfunc(entry: tuple[Documenter, bool]) -> int:
                     fullname = entry[0].name.split('::')[1]
                     return tagorder.get(fullname, len(tagorder))
                 documenters.sort(key=keyfunc)
-            else:
-                # Assume that member discovery order matches source order.
-                # This is a reasonable assumption in Python 3.6 and up, where
-                # module.__dict__ is insertion-ordered.
-                pass
         else:  # alphabetical
             documenters.sort(key=lambda e: e[0].name)
 
         return documenters
 
-    def generate(self, more_content: Optional[StringList] = None, real_modname: str = None,
-                 check_module: bool = False, all_members: bool = False) -> None:
+    def generate(
+        self,
+        more_content: StringList | None = None,
+        real_modname: str | None = None,
+        check_module: bool = False,
+        all_members: bool = False,
+    ) -> None:
         """Generate reST for the object given by *self.name*, and possibly for
         its members.
 
@@ -929,7 +892,7 @@ class Documenter:
         if not self.parse_name():
             # need a module to import
             logger.warning(
-                __('don\'t know which module to import for autodocumenting '
+                __("don't know which module to import for autodocumenting "
                    '%r (try placing a "module" or "currentmodule" directive '
                    'in the document, or giving an explicit module name)') %
                 self.name, type='autodoc')
@@ -971,8 +934,7 @@ class Documenter:
             except PycodeError:
                 pass
 
-        docstrings: List[str] = sum(self.get_doc() or [], [])
-
+        docstrings: list[str] = sum(self.get_doc() or [], [])
         if ismock(self.object) and not docstrings:
             logger.warning(__('A mocked object is detected: %r'),
                            self.name, type='autodoc')
@@ -1017,7 +979,7 @@ class ModuleDocumenter(Documenter):
     """
     objtype = 'module'
     content_indent = ''
-    titles_allowed = True
+    _extra_indent = '   '
 
     option_spec: OptionSpec = {
         'members': members_option, 'undoc-members': bool_option,
@@ -1026,22 +988,32 @@ class ModuleDocumenter(Documenter):
         'platform': identity, 'deprecated': bool_option,
         'member-order': member_order_option, 'exclude-members': exclude_members_option,
         'private-members': members_option, 'special-members': members_option,
-        'imported-members': bool_option, 'ignore-module-all': bool_option
+        'imported-members': bool_option, 'ignore-module-all': bool_option,
+        'no-value': bool_option,
     }
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
         merge_members_option(self.options)
-        self.__all__: Optional[Sequence[str]] = None
+        self.__all__: Sequence[str] | None = None
+
+    def add_content(self, more_content: StringList | None) -> None:
+        old_indent = self.indent
+        self.indent += self._extra_indent
+        super().add_content(None)
+        self.indent = old_indent
+        if more_content:
+            for line, src in zip(more_content.data, more_content.items):
+                self.add_line(line, src[0], src[1])
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         # don't document submodules automatically
         return False
 
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         if modname is not None:
             logger.warning(__('"::" in automodule name doesn\'t make sense'),
                            type='autodoc')
@@ -1082,14 +1054,14 @@ class ModuleDocumenter(Documenter):
         if self.options.deprecated:
             self.add_line('   :deprecated:', sourcename)
 
-    def get_module_members(self) -> Dict[str, ObjectMember]:
+    def get_module_members(self) -> dict[str, ObjectMember]:
         """Get members of target module."""
         if self.analyzer:
             attr_docs = self.analyzer.attr_docs
         else:
             attr_docs = {}
 
-        members: Dict[str, ObjectMember] = {}
+        members: dict[str, ObjectMember] = {}
         for name in dir(self.object):
             try:
                 value = safe_getattr(self.object, name, None)
@@ -1109,7 +1081,7 @@ class ModuleDocumenter(Documenter):
 
         return members
 
-    def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
         members = self.get_module_members()
         if want_all:
             if self.__all__ is None:
@@ -1135,14 +1107,14 @@ class ModuleDocumenter(Documenter):
                                    type='autodoc')
             return False, ret
 
-    def sort_members(self, documenters: List[Tuple["Documenter", bool]],
-                     order: str) -> List[Tuple["Documenter", bool]]:
+    def sort_members(self, documenters: list[tuple[Documenter, bool]],
+                     order: str) -> list[tuple[Documenter, bool]]:
         if order == 'bysource' and self.__all__:
             # Sort alphabetically first (for members not listed on the __all__)
             documenters.sort(key=lambda e: e[0].name)
 
             # Sort by __all__
-            def keyfunc(entry: Tuple[Documenter, bool]) -> int:
+            def keyfunc(entry: tuple[Documenter, bool]) -> int:
                 name = entry[0].name.split('::')[1]
                 if self.__all__ and name in self.__all__:
                     return self.__all__.index(name)
@@ -1160,8 +1132,8 @@ class ModuleLevelDocumenter(Documenter):
     Specialized Documenter subclass for objects on module level (functions,
     classes, data/constants).
     """
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         if modname is None:
             if path:
                 modname = path.rstrip('.')
@@ -1181,8 +1153,8 @@ class ClassLevelDocumenter(Documenter):
     Specialized Documenter subclass for objects on class level (methods,
     attributes).
     """
-    def resolve_name(self, modname: str, parents: Any, path: str, base: Any
-                     ) -> Tuple[str, List[str]]:
+    def resolve_name(self, modname: str, parents: Any, path: str, base: Any,
+                     ) -> tuple[str, list[str]]:
         if modname is None:
             if path:
                 mod_cls = path.rstrip('.')
@@ -1214,10 +1186,10 @@ class DocstringSignatureMixin:
     Mixin for FunctionDocumenter and MethodDocumenter to provide the
     feature of reading the signature from the docstring.
     """
-    _new_docstrings: List[List[str]] = None
-    _signatures: List[str] = None
+    _new_docstrings: list[list[str]] = None
+    _signatures: list[str] = None
 
-    def _find_signature(self) -> Tuple[str, str]:
+    def _find_signature(self) -> tuple[str | None, str | None]:
         # candidates of the object name
         valid_names = [self.objpath[-1]]  # type: ignore
         if isinstance(self, ClassDocumenter):
@@ -1253,14 +1225,14 @@ class DocstringSignatureMixin:
                 # re-prepare docstring to ignore more leading indentation
                 tab_width = self.directive.state.document.settings.tab_width  # type: ignore
                 self._new_docstrings[i] = prepare_docstring('\n'.join(doclines[j + 1:]),
-                                                            tabsize=tab_width)
+                                                            tab_width)
 
                 if result is None:
                     # first signature
                     result = args, retann
                 else:
                     # subsequent signatures
-                    self._signatures.append("(%s) -> %s" % (args, retann))
+                    self._signatures.append(f"({args}) -> {retann}")
 
             if result:
                 # finish the loop when signature found
@@ -1268,10 +1240,10 @@ class DocstringSignatureMixin:
 
         return result
 
-    def get_doc(self, ignore: int = None) -> List[List[str]]:
+    def get_doc(self) -> list[list[str]]:
         if self._new_docstrings is not None:
             return self._new_docstrings
-        return super().get_doc(ignore)  # type: ignore
+        return super().get_doc()  # type: ignore[misc]
 
     def format_signature(self, **kwargs: Any) -> str:
         if self.args is None and self.config.autodoc_docstring_signature:  # type: ignore
@@ -1293,7 +1265,10 @@ class DocstringStripSignatureMixin(DocstringSignatureMixin):
     feature of stripping any function signature from the docstring.
     """
     def format_signature(self, **kwargs: Any) -> str:
-        if self.args is None and self.config.autodoc_docstring_signature:  # type: ignore
+        if (
+            self.args is None
+            and self.config.autodoc_docstring_signature  # type: ignore[attr-defined]
+        ):
             # only act if a signature is not explicitly given already, and if
             # the feature is enabled
             result = self._find_signature()
@@ -1313,13 +1288,13 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
     member_order = 30
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         # supports functions, builtins and bound methods exported at the module level
         return (inspect.isfunction(member) or inspect.isbuiltin(member) or
                 (inspect.isroutine(member) and isinstance(parent, ModuleDocumenter)))
 
-    def format_args(self, **kwargs: Any) -> str:
+    def format_args(self, **kwargs: Any) -> str | None:
         if self.config.autodoc_typehints in ('none', 'description'):
             kwargs.setdefault('show_annotation', False)
         if self.config.autodoc_typehints_format == "short":
@@ -1402,7 +1377,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
 
         return overload.replace(parameters=parameters)
 
-    def annotate_to_first_argument(self, func: Callable, typ: Type) -> Optional[Callable]:
+    def annotate_to_first_argument(self, func: Callable, typ: type) -> Callable | None:
         """Annotate type hint to the first argument of function if needed."""
         try:
             sig = inspect.signature(func, type_aliases=self.config.autodoc_type_aliases)
@@ -1428,8 +1403,8 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
             except (AttributeError, TypeError):
                 # failed to update signature (ex. built-in or extension types)
                 return None
-        else:
-            return None
+
+        return func
 
 
 class DecoratorDocumenter(FunctionDocumenter):
@@ -1478,6 +1453,11 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         'class-doc-from': class_doc_from_option,
     }
 
+    # Must be higher than FunctionDocumenter, ClassDocumenter, and
+    # AttributeDocumenter as NewType can be an attribute and is a class
+    # after Python 3.10. Before 3.10 it is a kind of function object
+    priority = 15
+
     _signature_class: Any = None
     _signature_method_name: str = None
 
@@ -1497,9 +1477,10 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         merge_members_option(self.options)
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
-        return isinstance(member, type)
+        return isinstance(member, type) or (
+            isattr and (inspect.isNewType(member) or isinstance(member, TypeVar)))
 
     def import_object(self, raiseerror: bool = False) -> bool:
         ret = super().import_object(raiseerror)
@@ -1512,9 +1493,19 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
                 self.doc_as_attr = False
             else:
                 self.doc_as_attr = True
+            if inspect.isNewType(self.object) or isinstance(self.object, TypeVar):
+                modname = getattr(self.object, '__module__', self.modname)
+                if modname != self.modname and self.modname.startswith(modname):
+                    bases = self.modname[len(modname):].strip('.').split('.')
+                    self.objpath = bases + self.objpath
+                    self.modname = modname
         return ret
 
-    def _get_signature(self) -> Tuple[Optional[Any], Optional[str], Optional[Signature]]:
+    def _get_signature(self) -> tuple[Any | None, str | None, Signature | None]:
+        if inspect.isNewType(self.object) or isinstance(self.object, TypeVar):
+            # Suppress signature
+            return None, None, None
+
         def get_user_defined_function_or_method(obj: Any, attr: str) -> Any:
             """ Get the `attr` function or method from `obj`, if it is user-defined. """
             if inspect.is_builtin_class_method(obj, attr):
@@ -1537,7 +1528,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         call = get_user_defined_function_or_method(type(self.object), '__call__')
 
         if call is not None:
-            if "{0.__module__}.{0.__qualname__}".format(call) in _METACLASS_CALL_BLACKLIST:
+            if f"{call.__module__}.{call.__qualname__}" in _METACLASS_CALL_BLACKLIST:
                 call = None
 
         if call is not None:
@@ -1553,7 +1544,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         new = get_user_defined_function_or_method(self.object, '__new__')
 
         if new is not None:
-            if "{0.__module__}.{0.__qualname__}".format(new) in _CLASS_NEW_BLACKLIST:
+            if f"{new.__module__}.{new.__qualname__}" in _CLASS_NEW_BLACKLIST:
                 new = None
 
         if new is not None:
@@ -1592,7 +1583,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         # with __init__ in C and no `__text_signature__`.
         return None, None, None
 
-    def format_args(self, **kwargs: Any) -> str:
+    def format_args(self, **kwargs: Any) -> str | None:
         if self.config.autodoc_typehints in ('none', 'description'):
             kwargs.setdefault('show_annotation', False)
         if self.config.autodoc_typehints_format == "short":
@@ -1611,6 +1602,20 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
 
         return stringify_signature(sig, show_return_annotation=False, **kwargs)
 
+    def _find_signature(self) -> tuple[str, str]:
+        result = super()._find_signature()
+        if result is not None:
+            # Strip a return value from signature of constructor in docstring (first entry)
+            result = (result[0], None)
+
+        for i, sig in enumerate(self._signatures):
+            if sig.endswith(' -> None'):
+                # Strip a return value from signatures of constructor in docstring (subsequent
+                # entries)
+                self._signatures[i] = sig[:-8]
+
+        return result
+
     def format_signature(self, **kwargs: Any) -> str:
         if self.doc_as_attr:
             return ''
@@ -1643,7 +1648,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
 
         return "\n".join(sigs)
 
-    def get_overloaded_signatures(self) -> List[Signature]:
+    def get_overloaded_signatures(self) -> list[Signature]:
         if self._signature_class and self._signature_method_name:
             for cls in self._signature_class.__mro__:
                 try:
@@ -1651,7 +1656,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
                     analyzer.analyze()
                     qualname = '.'.join([cls.__qualname__, self._signature_method_name])
                     if qualname in analyzer.overloads:
-                        return analyzer.overloads.get(qualname)
+                        return analyzer.overloads.get(qualname, [])
                     elif qualname in analyzer.tagorder:
                         # the constructor is defined in the class, but not overridden.
                         return []
@@ -1660,7 +1665,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
 
         return []
 
-    def get_canonical_fullname(self) -> Optional[str]:
+    def get_canonical_fullname(self) -> str | None:
         __modname__ = safe_getattr(self.object, '__module__', self.modname)
         __qualname__ = safe_getattr(self.object, '__qualname__', None)
         if __qualname__ is None:
@@ -1681,18 +1686,22 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
             self.directivetype = 'attribute'
         super().add_directive_header(sig)
 
+        if inspect.isNewType(self.object) or isinstance(self.object, TypeVar):
+            return
+
         if self.analyzer and '.'.join(self.objpath) in self.analyzer.finals:
             self.add_line('   :final:', sourcename)
 
         canonical_fullname = self.get_canonical_fullname()
-        if not self.doc_as_attr and canonical_fullname and self.fullname != canonical_fullname:
+        if (not self.doc_as_attr and not inspect.isNewType(self.object)
+                and canonical_fullname and self.fullname != canonical_fullname):
             self.add_line('   :canonical: %s' % canonical_fullname, sourcename)
 
         # add inheritance info, if wanted
         if not self.doc_as_attr and self.options.show_inheritance:
             if inspect.getorigbases(self.object):
                 # A subclass of generic types
-                # refs: PEP-560 <https://www.python.org/dev/peps/pep-0560/>
+                # refs: PEP-560 <https://peps.python.org/pep-0560/>
                 bases = list(self.object.__orig_bases__)
             elif hasattr(self.object, '__bases__') and len(self.object.__bases__):
                 # A normal class
@@ -1712,14 +1721,15 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
             self.add_line('', sourcename)
             self.add_line('   ' + _('Bases: %s') % ', '.join(base_classes), sourcename)
 
-    def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:
-        members = get_class_members(self.object, self.objpath, self.get_attr)
+    def get_object_members(self, want_all: bool) -> tuple[bool, ObjectMembers]:
+        members = get_class_members(self.object, self.objpath, self.get_attr,
+                                    self.config.autodoc_inherit_docstrings)
         if not want_all:
             if not self.options.members:
                 return False, []  # type: ignore
             # specific members given
             selected = []
-            for name in self.options.members:  # type: str
+            for name in self.options.members:
                 if name in members:
                     selected.append(members[name])
                 else:
@@ -1731,7 +1741,28 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         else:
             return False, [m for m in members.values() if m.class_ == self.object]
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
+        if isinstance(self.object, TypeVar):
+            if self.object.__doc__ == TypeVar.__doc__:
+                return []
+        if sys.version_info[:2] < (3, 10):
+            if inspect.isNewType(self.object) or isinstance(self.object, TypeVar):
+                parts = self.modname.strip('.').split('.')
+                orig_objpath = self.objpath
+                for i in range(len(parts)):
+                    new_modname = '.'.join(parts[:len(parts) - i])
+                    new_objpath = parts[len(parts) - i:] + orig_objpath
+                    try:
+                        analyzer = ModuleAnalyzer.for_module(new_modname)
+                        analyzer.analyze()
+                        key = ('', new_objpath[-1])
+                        comment = list(analyzer.attr_docs.get(key, []))
+                        if comment:
+                            self.objpath = new_objpath
+                            self.modname = new_modname
+                            return [comment]
+                    except PycodeError:
+                        pass
         if self.doc_as_attr:
             # Don't show the docstring of the class when it is an alias.
             comment = self.get_variable_comment()
@@ -1811,9 +1842,9 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
                 docstrings[i] = mint_doc
 
         tab_width = self.directive.state.document.settings.tab_width
-        return [prepare_docstring(docstring, ignore, tab_width) for docstring in docstrings]
+        return [prepare_docstring(docstring, tab_width) for docstring in docstrings]
 
-    def get_variable_comment(self) -> Optional[List[str]]:
+    def get_variable_comment(self) -> list[str] | None:
         try:
             key = ('', '.'.join(self.objpath))
             if self.doc_as_attr:
@@ -1825,12 +1856,43 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         except PycodeError:
             return None
 
-    def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
-                    ) -> None:
+    def add_content(self, more_content: StringList | None) -> None:
+        if inspect.isNewType(self.object):
+            if self.config.autodoc_typehints_format == "short":
+                supertype = restify(self.object.__supertype__, "smart")
+            else:
+                supertype = restify(self.object.__supertype__)
+
+            more_content = StringList([_('alias of %s') % supertype, ''], source='')
+        if isinstance(self.object, TypeVar):
+            attrs = [repr(self.object.__name__)]
+            for constraint in self.object.__constraints__:
+                if self.config.autodoc_typehints_format == "short":
+                    attrs.append(stringify_annotation(constraint, "smart"))
+                else:
+                    attrs.append(stringify_annotation(constraint))
+            if self.object.__bound__:
+                if self.config.autodoc_typehints_format == "short":
+                    bound = restify(self.object.__bound__, "smart")
+                else:
+                    bound = restify(self.object.__bound__)
+                attrs.append(r"bound=\ " + bound)
+            if self.object.__covariant__:
+                attrs.append("covariant=True")
+            if self.object.__contravariant__:
+                attrs.append("contravariant=True")
+
+            more_content = StringList(
+                [_('alias of TypeVar(%s)') % ", ".join(attrs), ''],
+                source='',
+            )
         if self.doc_as_attr and self.modname != self.get_real_modname():
-            # override analyzer to obtain doccomment around its definition.
-            self.analyzer = ModuleAnalyzer.for_module(self.modname)
-            self.analyzer.analyze()
+            try:
+                # override analyzer to obtain doccomment around its definition.
+                self.analyzer = ModuleAnalyzer.for_module(self.modname)
+                self.analyzer.analyze()
+            except PycodeError:
+                pass
 
         if self.doc_as_attr and not self.get_variable_comment():
             try:
@@ -1849,8 +1911,13 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
             return
         super().document_members(all_members)
 
-    def generate(self, more_content: Optional[StringList] = None, real_modname: str = None,
-                 check_module: bool = False, all_members: bool = False) -> None:
+    def generate(
+        self,
+        more_content: StringList | None = None,
+        real_modname: str | None = None,
+        check_module: bool = False,
+        all_members: bool = False,
+    ) -> None:
         # Do not pass real_modname and use the name from the __module__
         # attribute of the class.
         # If a class gets imported into the module real_modname
@@ -1869,10 +1936,10 @@ class ExceptionDocumenter(ClassDocumenter):
     member_order = 10
 
     # needs a higher priority than ClassDocumenter
-    priority = 10
+    priority = ClassDocumenter.priority + 5
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         return isinstance(member, type) and issubclass(member, BaseException)
 
@@ -1884,7 +1951,7 @@ class DataDocumenterMixinBase:
     modname: str = None
     parent: Any = None
     object: Any = None
-    objpath: List[str] = None
+    objpath: list[str] = None
 
     def should_suppress_directive_header(self) -> bool:
         """Check directive header should be suppressed."""
@@ -1895,7 +1962,7 @@ class DataDocumenterMixinBase:
         return False
 
     def update_content(self, more_content: StringList) -> None:
-        """Update docstring for the NewType object."""
+        """Update docstring, for example with TypeVar variance."""
         pass
 
 
@@ -1922,75 +1989,6 @@ class GenericAliasMixin(DataDocumenterMixinBase):
         super().update_content(more_content)
 
 
-class NewTypeMixin(DataDocumenterMixinBase):
-    """
-    Mixin for DataDocumenter and AttributeDocumenter to provide the feature for
-    supporting NewTypes.
-    """
-
-    def should_suppress_directive_header(self) -> bool:
-        return (inspect.isNewType(self.object) or
-                super().should_suppress_directive_header())
-
-    def update_content(self, more_content: StringList) -> None:
-        if inspect.isNewType(self.object):
-            if self.config.autodoc_typehints_format == "short":
-                supertype = restify(self.object.__supertype__, "smart")
-            else:
-                supertype = restify(self.object.__supertype__)
-
-            more_content.append(_('alias of %s') % supertype, '')
-            more_content.append('', '')
-
-        super().update_content(more_content)
-
-
-class TypeVarMixin(DataDocumenterMixinBase):
-    """
-    Mixin for DataDocumenter and AttributeDocumenter to provide the feature for
-    supporting TypeVars.
-    """
-
-    def should_suppress_directive_header(self) -> bool:
-        return (isinstance(self.object, TypeVar) or
-                super().should_suppress_directive_header())
-
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
-        if ignore is not None:
-            warnings.warn("The 'ignore' argument to autodoc.%s.get_doc() is deprecated."
-                          % self.__class__.__name__,
-                          RemovedInSphinx50Warning, stacklevel=2)
-
-        if isinstance(self.object, TypeVar):
-            if self.object.__doc__ != TypeVar.__doc__:
-                return super().get_doc()  # type: ignore
-            else:
-                return []
-        else:
-            return super().get_doc()  # type: ignore
-
-    def update_content(self, more_content: StringList) -> None:
-        if isinstance(self.object, TypeVar):
-            attrs = [repr(self.object.__name__)]
-            for constraint in self.object.__constraints__:
-                attrs.append(stringify_typehint(constraint))
-            if self.object.__bound__:
-                if self.config.autodoc_typehints_format == "short":
-                    bound = restify(self.object.__bound__, "smart")
-                else:
-                    bound = restify(self.object.__bound__)
-                attrs.append(r"bound=\ " + bound)
-            if self.object.__covariant__:
-                attrs.append("covariant=True")
-            if self.object.__contravariant__:
-                attrs.append("contravariant=True")
-
-            more_content.append(_('alias of TypeVar(%s)') % ", ".join(attrs), '')
-            more_content.append('', '')
-
-        super().update_content(more_content)
-
-
 class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
     """
     Mixin for DataDocumenter to provide the feature for supporting uninitialized
@@ -2016,23 +2014,22 @@ class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
 
             if raiseerror:
                 raise
-            else:
-                logger.warning(exc.args[0], type='autodoc', subtype='import_object')
-                self.env.note_reread()
-                return False
+            logger.warning(exc.args[0], type='autodoc', subtype='import_object')
+            self.env.note_reread()
+            return False
 
     def should_suppress_value_header(self) -> bool:
         return (self.object is UNINITIALIZED_ATTR or
                 super().should_suppress_value_header())
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
         if self.object is UNINITIALIZED_ATTR:
             return []
         else:
-            return super().get_doc(ignore)  # type: ignore
+            return super().get_doc()  # type: ignore
 
 
-class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
+class DataDocumenter(GenericAliasMixin,
                      UninitializedGlobalVariableMixin, ModuleLevelDocumenter):
     """
     Specialized Documenter subclass for data items.
@@ -2045,7 +2042,7 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
     option_spec["no-value"] = bool_option
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         return isinstance(parent, ModuleDocumenter) and isattr
 
@@ -2095,7 +2092,12 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
                 annotations = get_type_hints(self.parent, None,
                                              self.config.autodoc_type_aliases)
                 if self.objpath[-1] in annotations:
-                    objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
+                    if self.config.autodoc_typehints_format == "short":
+                        objrepr = stringify_annotation(annotations.get(self.objpath[-1]),
+                                                       "smart")
+                    else:
+                        objrepr = stringify_annotation(annotations.get(self.objpath[-1]),
+                                                       "fully-qualified-except-typing")
                     self.add_line('   :type: ' + objrepr, sourcename)
 
             try:
@@ -2115,7 +2117,7 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
         real_modname = self.get_attr(self.parent or self.object, '__module__', None)
         return real_modname or self.modname
 
-    def get_module_comment(self, attrname: str) -> Optional[List[str]]:
+    def get_module_comment(self, attrname: str) -> list[str] | None:
         try:
             analyzer = ModuleAnalyzer.for_module(self.modname)
             analyzer.analyze()
@@ -2127,16 +2129,15 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
 
         return None
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
         # Check the variable has a docstring-comment
         comment = self.get_module_comment(self.objpath[-1])
         if comment:
             return [comment]
         else:
-            return super().get_doc(ignore)
+            return super().get_doc()
 
-    def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
-                    ) -> None:
+    def add_content(self, more_content: StringList | None) -> None:
         # Disable analyzing variable comment on Documenter.add_content() to control it on
         # DataDocumenter.add_content()
         self.analyzer = None
@@ -2145,25 +2146,7 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
             more_content = StringList()
 
         self.update_content(more_content)
-        super().add_content(more_content, no_docstring=no_docstring)
-
-
-class NewTypeDataDocumenter(DataDocumenter):
-    """
-    Specialized Documenter subclass for NewTypes.
-
-    Note: This must be invoked before FunctionDocumenter because NewType is a kind of
-    function object.
-    """
-
-    objtype = 'newtypedata'
-    directivetype = 'data'
-    priority = FunctionDocumenter.priority + 1
-
-    @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
-                            ) -> bool:
-        return inspect.isNewType(member) and isattr
+        super().add_content(more_content)
 
 
 class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type: ignore
@@ -2176,7 +2159,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
     priority = 1  # must be more than FunctionDocumenter
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         return inspect.isroutine(member) and not isinstance(parent, ModuleDocumenter)
 
@@ -2197,7 +2180,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
 
         return ret
 
-    def format_args(self, **kwargs: Any) -> str:
+    def format_args(self, **kwargs: Any) -> str | None:
         if self.config.autodoc_typehints in ('none', 'description'):
             kwargs.setdefault('show_annotation', False)
         if self.config.autodoc_typehints_format == "short":
@@ -2313,7 +2296,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
 
         return overload.replace(parameters=parameters)
 
-    def annotate_to_first_argument(self, func: Callable, typ: Type) -> Optional[Callable]:
+    def annotate_to_first_argument(self, func: Callable, typ: type) -> Callable | None:
         """Annotate type hint to the first argument of function if needed."""
         try:
             sig = inspect.signature(func, type_aliases=self.config.autodoc_type_aliases)
@@ -2339,10 +2322,10 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
             except (AttributeError, TypeError):
                 # failed to update signature (ex. built-in or extension types)
                 return None
-        else:
-            return None
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+        return func
+
+    def get_doc(self) -> list[list[str]] | None:
         if self._new_docstrings is not None:
             # docstring already returned previously, then modified by
             # `DocstringSignatureMixin`.  Just return the previously-computed
@@ -2401,13 +2384,13 @@ class NonDataDescriptorMixin(DataDocumenterMixinBase):
         return (not getattr(self, 'non_data_descriptor', False) or
                 super().should_suppress_directive_header())
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
         if getattr(self, 'non_data_descriptor', False):
             # the docstring of non datadescriptor is very probably the wrong thing
             # to display
             return None
         else:
-            return super().get_doc(ignore)  # type: ignore
+            return super().get_doc()  # type: ignore
 
 
 class SlotsMixin(DataDocumenterMixinBase):
@@ -2419,10 +2402,7 @@ class SlotsMixin(DataDocumenterMixinBase):
         """Check the subject is an attribute in __slots__."""
         try:
             __slots__ = inspect.getslots(self.parent)
-            if __slots__ and self.objpath[-1] in __slots__:
-                return True
-            else:
-                return False
+            return bool(__slots__) and self.objpath[-1] in __slots__
         except (ValueError, TypeError):
             return False
 
@@ -2439,7 +2419,7 @@ class SlotsMixin(DataDocumenterMixinBase):
         else:
             return super().should_suppress_value_header()
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
         if self.object is SLOTSATTR:
             try:
                 __slots__ = inspect.getslots(self.parent)
@@ -2453,16 +2433,7 @@ class SlotsMixin(DataDocumenterMixinBase):
                                (self.parent.__qualname__, exc), type='autodoc')
                 return []
         else:
-            return super().get_doc(ignore)  # type: ignore
-
-    @property
-    def _datadescriptor(self) -> bool:
-        warnings.warn('AttributeDocumenter._datadescriptor() is deprecated.',
-                      RemovedInSphinx60Warning)
-        if self.object is SLOTSATTR:
-            return True
-        else:
-            return False
+            return super().get_doc()  # type: ignore
 
 
 class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
@@ -2484,10 +2455,9 @@ class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
         # An instance variable defined in __init__().
         if self.get_attribute_comment(parent, self.objpath[-1]):  # type: ignore
             return True
-        elif self.is_runtime_instance_attribute_not_commented(parent):
+        if self.is_runtime_instance_attribute_not_commented(parent):
             return True
-        else:
-            return False
+        return False
 
     def is_runtime_instance_attribute_not_commented(self, parent: Any) -> bool:
         """Check the subject is an attribute defined in __init__() without comment."""
@@ -2528,21 +2498,20 @@ class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
 
             if raiseerror:
                 raise
-            else:
-                logger.warning(exc.args[0], type='autodoc', subtype='import_object')
-                self.env.note_reread()
-                return False
+            logger.warning(exc.args[0], type='autodoc', subtype='import_object')
+            self.env.note_reread()
+            return False
 
     def should_suppress_value_header(self) -> bool:
         return (self.object is self.RUNTIME_INSTANCE_ATTRIBUTE or
                 super().should_suppress_value_header())
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
         if (self.object is self.RUNTIME_INSTANCE_ATTRIBUTE and
                 self.is_runtime_instance_attribute_not_commented(self.parent)):
             return None
         else:
-            return super().get_doc(ignore)  # type: ignore
+            return super().get_doc()  # type: ignore
 
 
 class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
@@ -2559,10 +2528,7 @@ class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
     def is_uninitialized_instance_attribute(self, parent: Any) -> bool:
         """Check the subject is an annotation only attribute."""
         annotations = get_type_hints(parent, None, self.config.autodoc_type_aliases)
-        if self.objpath[-1] in annotations:
-            return True
-        else:
-            return False
+        return self.objpath[-1] in annotations
 
     def import_object(self, raiseerror: bool = False) -> bool:
         """Check the exisitence of uninitialized instance attribute when failed to import
@@ -2584,24 +2550,23 @@ class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
 
             if raiseerror:
                 raise
-            else:
-                logger.warning(exc.args[0], type='autodoc', subtype='import_object')
-                self.env.note_reread()
-                return False
+            logger.warning(exc.args[0], type='autodoc', subtype='import_object')
+            self.env.note_reread()
+            return False
 
     def should_suppress_value_header(self) -> bool:
         return (self.object is UNINITIALIZED_ATTR or
                 super().should_suppress_value_header())
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
         if self.object is UNINITIALIZED_ATTR:
             return None
         else:
-            return super().get_doc(ignore)  # type: ignore
+            return super().get_doc()  # type: ignore
 
 
-class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type: ignore
-                          TypeVarMixin, RuntimeInstanceAttributeMixin,
+class AttributeDocumenter(GenericAliasMixin, SlotsMixin,  # type: ignore
+                          RuntimeInstanceAttributeMixin,
                           UninitializedInstanceAttributeMixin, NonDataDescriptorMixin,
                           DocstringStripSignatureMixin, ClassLevelDocumenter):
     """
@@ -2622,41 +2587,19 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
         return inspect.isfunction(obj) or inspect.isbuiltin(obj) or inspect.ismethod(obj)
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         if isinstance(parent, ModuleDocumenter):
             return False
-        elif inspect.isattributedescriptor(member):
+        if inspect.isattributedescriptor(member):
             return True
-        elif not inspect.isroutine(member) and not isinstance(member, type):
+        if not inspect.isroutine(member) and not isinstance(member, type):
             return True
-        else:
-            return False
+        return False
 
     def document_members(self, all_members: bool = False) -> None:
         pass
 
-    def isinstanceattribute(self) -> bool:
-        """Check the subject is an instance attribute."""
-        warnings.warn('AttributeDocumenter.isinstanceattribute() is deprecated.',
-                      RemovedInSphinx50Warning)
-        # uninitialized instance variable (PEP-526)
-        with mock(self.config.autodoc_mock_imports):
-            try:
-                ret = import_object(self.modname, self.objpath[:-1], 'class',
-                                    attrgetter=self.get_attr,
-                                    warningiserror=self.config.autodoc_warningiserror)
-                self.parent = ret[3]
-                annotations = get_type_hints(self.parent, None,
-                                             self.config.autodoc_type_aliases)
-                if self.objpath[-1] in annotations:
-                    self.object = UNINITIALIZED_ATTR
-                    return True
-            except ImportError:
-                pass
-
-        return False
-
     def update_annotations(self, parent: Any) -> None:
         """Update __annotations__ to support type_comment and so on."""
         try:
@@ -2717,7 +2660,12 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
                 annotations = get_type_hints(self.parent, None,
                                              self.config.autodoc_type_aliases)
                 if self.objpath[-1] in annotations:
-                    objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
+                    if self.config.autodoc_typehints_format == "short":
+                        objrepr = stringify_annotation(annotations.get(self.objpath[-1]),
+                                                       "smart")
+                    else:
+                        objrepr = stringify_annotation(annotations.get(self.objpath[-1]),
+                                                       "fully-qualified-except-typing")
                     self.add_line('   :type: ' + objrepr, sourcename)
 
             try:
@@ -2730,7 +2678,7 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
             except ValueError:
                 pass
 
-    def get_attribute_comment(self, parent: Any, attrname: str) -> Optional[List[str]]:
+    def get_attribute_comment(self, parent: Any, attrname: str) -> list[str] | None:
         for cls in inspect.getmro(parent):
             try:
                 module = safe_getattr(cls, '__module__')
@@ -2747,7 +2695,7 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
 
         return None
 
-    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+    def get_doc(self) -> list[list[str]] | None:
         # Check the attribute has a docstring-comment
         comment = self.get_attribute_comment(self.parent, self.objpath[-1])
         if comment:
@@ -2759,12 +2707,11 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
             # ref: https://github.com/sphinx-doc/sphinx/issues/7805
             orig = self.config.autodoc_inherit_docstrings
             self.config.autodoc_inherit_docstrings = False  # type: ignore
-            return super().get_doc(ignore)
+            return super().get_doc()
         finally:
             self.config.autodoc_inherit_docstrings = orig  # type: ignore
 
-    def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
-                    ) -> None:
+    def add_content(self, more_content: StringList | None) -> None:
         # Disable analyzing attribute comment on Documenter.add_content() to control it on
         # AttributeDocumenter.add_content()
         self.analyzer = None
@@ -2772,7 +2719,7 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
         if more_content is None:
             more_content = StringList()
         self.update_content(more_content)
-        super().add_content(more_content, no_docstring)
+        super().add_content(more_content)
 
 
 class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  # type: ignore
@@ -2786,7 +2733,7 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  #
     priority = AttributeDocumenter.priority + 1
 
     @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
+    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any,
                             ) -> bool:
         if isinstance(parent, ClassDocumenter):
             if inspect.isproperty(member):
@@ -2815,6 +2762,16 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  #
         self.isclassmethod = False
         return ret
 
+    def format_args(self, **kwargs: Any) -> str | None:
+        func = self._get_property_getter()
+        if func is None:
+            return None
+
+        # update the annotations of the property getter
+        self.env.app.emit('autodoc-before-process-signature', func, False)
+        # correctly format the arguments for a property
+        return super().format_args(**kwargs)
+
     def document_members(self, all_members: bool = False) -> None:
         pass
 
@@ -2830,50 +2787,33 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  #
         if self.isclassmethod:
             self.add_line('   :classmethod:', sourcename)
 
-        if safe_getattr(self.object, 'fget', None):  # property
-            func = self.object.fget
-        elif safe_getattr(self.object, 'func', None):  # cached_property
-            func = self.object.func
-        else:
-            func = None
-
-        if func and self.config.autodoc_typehints != 'none':
-            try:
-                signature = inspect.signature(func,
-                                              type_aliases=self.config.autodoc_type_aliases)
-                if signature.return_annotation is not Parameter.empty:
-                    objrepr = stringify_typehint(signature.return_annotation)
-                    self.add_line('   :type: ' + objrepr, sourcename)
-            except TypeError as exc:
-                logger.warning(__("Failed to get a function signature for %s: %s"),
-                               self.fullname, exc)
-                return None
-            except ValueError:
-                return None
-
-
-class NewTypeAttributeDocumenter(AttributeDocumenter):
-    """
-    Specialized Documenter subclass for NewTypes.
-
-    Note: This must be invoked before MethodDocumenter because NewType is a kind of
-    function object.
-    """
-
-    objtype = 'newvarattribute'
-    directivetype = 'attribute'
-    priority = MethodDocumenter.priority + 1
-
-    @classmethod
-    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
-                            ) -> bool:
-        return not isinstance(parent, ModuleDocumenter) and inspect.isNewType(member)
+        func = self._get_property_getter()
+        if func is None or self.config.autodoc_typehints == 'none':
+            return
 
+        try:
+            signature = inspect.signature(func,
+                                          type_aliases=self.config.autodoc_type_aliases)
+            if signature.return_annotation is not Parameter.empty:
+                if self.config.autodoc_typehints_format == "short":
+                    objrepr = stringify_annotation(signature.return_annotation, "smart")
+                else:
+                    objrepr = stringify_annotation(signature.return_annotation,
+                                                   "fully-qualified-except-typing")
+                self.add_line('   :type: ' + objrepr, sourcename)
+        except TypeError as exc:
+            logger.warning(__("Failed to get a function signature for %s: %s"),
+                           self.fullname, exc)
+            pass
+        except ValueError:
+            pass
 
-def get_documenters(app: Sphinx) -> Dict[str, Type[Documenter]]:
-    """Returns registered Documenter classes"""
-    warnings.warn("get_documenters() is deprecated.", RemovedInSphinx50Warning, stacklevel=2)
-    return app.registry.documenters
+    def _get_property_getter(self):
+        if safe_getattr(self.object, 'fget', None):  # property
+            return self.object.fget
+        if safe_getattr(self.object, 'func', None):  # cached_property
+            return self.object.func
+        return None
 
 
 def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
@@ -2885,40 +2825,20 @@ def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
     return safe_getattr(obj, name, *defargs)
 
 
-def migrate_autodoc_member_order(app: Sphinx, config: Config) -> None:
-    if config.autodoc_member_order == 'alphabetic':
-        # RemovedInSphinx50Warning
-        logger.warning(__('autodoc_member_order now accepts "alphabetical" '
-                          'instead of "alphabetic". Please update your setting.'))
-        config.autodoc_member_order = 'alphabetical'  # type: ignore
-
-
-# for compatibility
-from sphinx.ext.autodoc.deprecated import DataDeclarationDocumenter  # NOQA
-from sphinx.ext.autodoc.deprecated import GenericAliasDocumenter  # NOQA
-from sphinx.ext.autodoc.deprecated import InstanceAttributeDocumenter  # NOQA
-from sphinx.ext.autodoc.deprecated import SingledispatchFunctionDocumenter  # NOQA
-from sphinx.ext.autodoc.deprecated import SingledispatchMethodDocumenter  # NOQA
-from sphinx.ext.autodoc.deprecated import SlotsAttributeDocumenter  # NOQA
-from sphinx.ext.autodoc.deprecated import TypeVarDocumenter  # NOQA
-
-
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_autodocumenter(ModuleDocumenter)
     app.add_autodocumenter(ClassDocumenter)
     app.add_autodocumenter(ExceptionDocumenter)
     app.add_autodocumenter(DataDocumenter)
-    app.add_autodocumenter(NewTypeDataDocumenter)
     app.add_autodocumenter(FunctionDocumenter)
     app.add_autodocumenter(DecoratorDocumenter)
     app.add_autodocumenter(MethodDocumenter)
     app.add_autodocumenter(AttributeDocumenter)
     app.add_autodocumenter(PropertyDocumenter)
-    app.add_autodocumenter(NewTypeAttributeDocumenter)
 
     app.add_config_value('autoclass_content', 'class', True, ENUM('both', 'class', 'init'))
     app.add_config_value('autodoc_member_order', 'alphabetical', True,
-                         ENUM('alphabetic', 'alphabetical', 'bysource', 'groupwise'))
+                         ENUM('alphabetical', 'bysource', 'groupwise'))
     app.add_config_value('autodoc_class_signature', 'mixed', True, ENUM('mixed', 'separated'))
     app.add_config_value('autodoc_default_options', {}, True)
     app.add_config_value('autodoc_docstring_signature', True, True)
@@ -2926,9 +2846,9 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autodoc_typehints', "signature", True,
                          ENUM("signature", "description", "none", "both"))
     app.add_config_value('autodoc_typehints_description_target', 'all', True,
-                         ENUM('all', 'documented'))
+                         ENUM('all', 'documented', 'documented_params'))
     app.add_config_value('autodoc_type_aliases', {}, True)
-    app.add_config_value('autodoc_typehints_format', "fully-qualified", 'env',
+    app.add_config_value('autodoc_typehints_format', "short", 'env',
                          ENUM("fully-qualified", "short"))
     app.add_config_value('autodoc_warningiserror', True, True)
     app.add_config_value('autodoc_inherit_docstrings', True, True)
@@ -2938,8 +2858,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_event('autodoc-skip-member')
     app.add_event('autodoc-process-bases')
 
-    app.connect('config-inited', migrate_autodoc_member_order, priority=800)
-
     app.setup_extension('sphinx.ext.autodoc.preserve_defaults')
     app.setup_extension('sphinx.ext.autodoc.type_comment')
     app.setup_extension('sphinx.ext.autodoc.typehints')
diff --git a/docs/mindspore/_ext/overwriteautosummary_generate.txt b/docs/mindspore/_ext/overwriteautosummary_generate.txt
index 6014b006a3c3587ffe4f921be187489078918fc2..51163af969addc818e0665da15fd8f024e6d8f0c 100644
--- a/docs/mindspore/_ext/overwriteautosummary_generate.txt
+++ b/docs/mindspore/_ext/overwriteautosummary_generate.txt
@@ -1,22 +1,19 @@
-"""
-    sphinx.ext.autosummary.generate
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Usable as a library or script to generate automatic RST source files for
-    items referred to in autosummary:: directives.
+"""Generates reST source files for autosummary.
 
-    Each generated RST file contains a single auto*:: directive which
-    extracts the docstring of the referred item.
+Usable as a library or script to generate automatic RST source files for
+items referred to in autosummary:: directives.
 
-    Example Makefile rule::
+Each generated RST file contains a single auto*:: directive which
+extracts the docstring of the referred item.
 
-       generate:
-               sphinx-autogen -o source/generated source/*.rst
+Example Makefile rule::
 
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
+   generate:
+           sphinx-autogen -o source/generated source/*.rst
 """
 
+from __future__ import annotations
+
 import argparse
 import importlib
 import inspect
@@ -26,10 +23,8 @@ import pkgutil
 import pydoc
 import re
 import sys
-import warnings
-from gettext import NullTranslations
 from os import path
-from typing import Any, Dict, List, NamedTuple, Sequence, Set, Tuple, Type, Union
+from typing import TYPE_CHECKING, Any, NamedTuple, Sequence
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -39,11 +34,14 @@ from sphinx import __display_version__, package_dir
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.config import Config
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.ext.autodoc import Documenter
 from sphinx.ext.autodoc.importer import import_module
-from sphinx.ext.autosummary import (ImportExceptionGroup, get_documenter, import_by_name,
-                                    import_ivar_by_name)
+from sphinx.ext.autosummary import (
+    ImportExceptionGroup,
+    get_documenter,
+    import_by_name,
+    import_ivar_by_name,
+)
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.registry import SphinxComponentRegistry
@@ -52,6 +50,9 @@ from sphinx.util.inspect import getall, safe_getattr
 from sphinx.util.osutil import ensuredir
 from sphinx.util.template import SphinxTemplateLoader
 
+if TYPE_CHECKING:
+    from gettext import NullTranslations
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,7 +62,7 @@ class DummyApplication:
     def __init__(self, translator: NullTranslations) -> None:
         self.config = Config()
         self.registry = SphinxComponentRegistry()
-        self.messagelog: List[str] = []
+        self.messagelog: list[str] = []
         self.srcdir = "/"
         self.translator = translator
         self.verbosity = 0
@@ -95,32 +96,26 @@ class AutosummaryEntry(NamedTuple):
 
 
 def setup_documenters(app: Any) -> None:
-    from sphinx.ext.autodoc import (AttributeDocumenter, ClassDocumenter, DataDocumenter,
-                                    DecoratorDocumenter, ExceptionDocumenter,
-                                    FunctionDocumenter, MethodDocumenter, ModuleDocumenter,
-                                    NewTypeAttributeDocumenter, NewTypeDataDocumenter,
-                                    PropertyDocumenter)
-    documenters: List[Type[Documenter]] = [
+    from sphinx.ext.autodoc import (
+        AttributeDocumenter,
+        ClassDocumenter,
+        DataDocumenter,
+        DecoratorDocumenter,
+        ExceptionDocumenter,
+        FunctionDocumenter,
+        MethodDocumenter,
+        ModuleDocumenter,
+        PropertyDocumenter,
+    )
+    documenters: list[type[Documenter]] = [
         ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter,
-        FunctionDocumenter, MethodDocumenter, NewTypeAttributeDocumenter,
-        NewTypeDataDocumenter, AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
+        FunctionDocumenter, MethodDocumenter,
+        AttributeDocumenter, DecoratorDocumenter, PropertyDocumenter,
     ]
     for documenter in documenters:
         app.registry.add_documenter(documenter.objtype, documenter)
 
 
-def _simple_info(msg: str) -> None:
-    warnings.warn('_simple_info() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print(msg)
-
-
-def _simple_warn(msg: str) -> None:
-    warnings.warn('_simple_warn() is deprecated.',
-                  RemovedInSphinx50Warning, stacklevel=2)
-    print('WARNING: ' + msg, file=sys.stderr)
-
-
 def _underline(title: str, line: str = '=') -> str:
     if '\n' in title:
         raise ValueError('Can only underline single lines')
@@ -130,14 +125,9 @@ def _underline(title: str, line: str = '=') -> str:
 class AutosummaryRenderer:
     """A helper class for rendering."""
 
-    def __init__(self, app: Union[Builder, Sphinx], template_dir: str = None) -> None:
+    def __init__(self, app: Sphinx) -> None:
         if isinstance(app, Builder):
-            warnings.warn('The first argument for AutosummaryRenderer has been '
-                          'changed to Sphinx object',
-                          RemovedInSphinx50Warning, stacklevel=2)
-        if template_dir:
-            warnings.warn('template_dir argument for AutosummaryRenderer is deprecated.',
-                          RemovedInSphinx50Warning, stacklevel=2)
+            raise ValueError('Expected a Sphinx application object!')
 
         system_templates_path = [os.path.join(package_dir, 'ext', 'autosummary', 'templates')]
         loader = SphinxTemplateLoader(app.srcdir, app.config.templates_path,
@@ -148,26 +138,11 @@ class AutosummaryRenderer:
         self.env.filters['e'] = rst.escape
         self.env.filters['underline'] = _underline
 
-        if isinstance(app, (Sphinx, DummyApplication)):
-            if app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.translator)
-        elif isinstance(app, Builder):
-            if app.app.translator:
-                self.env.add_extension("jinja2.ext.i18n")
-                self.env.install_gettext_translations(app.app.translator)
-
-    def exists(self, template_name: str) -> bool:
-        """Check if template file exists."""
-        warnings.warn('AutosummaryRenderer.exists() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-        try:
-            self.env.get_template(template_name)
-            return True
-        except TemplateNotFound:
-            return False
+        if app.translator:
+            self.env.add_extension("jinja2.ext.i18n")
+            self.env.install_gettext_translations(app.translator)
 
-    def render(self, template_name: str, context: Dict) -> str:
+    def render(self, template_name: str, context: dict) -> str:
         """Render a template file."""
         try:
             template = self.env.get_template(template_name)
@@ -203,8 +178,14 @@ class ModuleScanner:
                            name, exc, type='autosummary')
             return False
 
-    def scan(self, imported_members: bool) -> List[str]:
+    def scan(self, imported_members: bool) -> list[str]:
         members = []
+        try:
+            analyzer = ModuleAnalyzer.for_module(self.object.__name__)
+            attr_docs = analyzer.find_attr_docs()
+        except PycodeError:
+            attr_docs = {}
+
         for name in members_of(self.object, self.app.config):
             try:
                 value = safe_getattr(self.object, name)
@@ -216,7 +197,9 @@ class ModuleScanner:
                 continue
 
             try:
-                if inspect.ismodule(value):
+                if ('', name) in attr_docs:
+                    imported = False
+                elif inspect.ismodule(value):  # NoQA: SIM114
                     imported = True
                 elif safe_getattr(value, '__module__') != self.object.__name__:
                     imported = True
@@ -226,14 +209,14 @@ class ModuleScanner:
                 imported = False
 
             respect_module_all = not self.app.config.autosummary_ignore_module_all
-            if imported_members:
+            if (
                 # list all members up
-                members.append(name)
-            elif imported is False:
+                imported_members
                 # list not-imported members
-                members.append(name)
-            elif '__all__' in dir(self.object) and respect_module_all:
+                or imported is False
                 # list members that have __all__ set
+                or (respect_module_all and '__all__' in dir(self.object))
+            ):
                 members.append(name)
 
         return members
@@ -253,8 +236,9 @@ def members_of(obj: Any, conf: Config) -> Sequence[str]:
 def generate_autosummary_content(name: str, obj: Any, parent: Any,
                                  template: AutosummaryRenderer, template_name: str,
                                  imported_members: bool, app: Any,
-                                 recursive: bool, context: Dict,
-                                 modname: str = None, qualname: str = None) -> str:
+                                 recursive: bool, context: dict,
+                                 modname: str | None = None,
+                                 qualname: str | None = None) -> str:
     doc = get_documenter(app, obj, parent)
 
     def skip_member(obj: Any, name: str, objtype: str) -> bool:
@@ -267,11 +251,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                            name, exc, type='autosummary')
             return False
 
-    def get_class_members(obj: Any) -> Dict[str, Any]:
+    def get_class_members(obj: Any) -> dict[str, Any]:
         members = sphinx.ext.autodoc.get_class_members(obj, [qualname], safe_getattr)
         return {name: member.object for name, member in members.items()}
 
-    def get_module_members(obj: Any) -> Dict[str, Any]:
+    def get_module_members(obj: Any) -> dict[str, Any]:
         members = {}
         for name in members_of(obj, app.config):
             try:
@@ -280,17 +264,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 continue
         return members
 
-    def get_all_members(obj: Any) -> Dict[str, Any]:
+    def get_all_members(obj: Any) -> dict[str, Any]:
         if doc.objtype == "module":
             return get_module_members(obj)
         elif doc.objtype == "class":
             return get_class_members(obj)
         return {}
 
-    def get_members(obj: Any, types: Set[str], include_public: List[str] = [],
-                    imported: bool = True) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
-        public: List[str] = []
+    def get_members(obj: Any, types: set[str], include_public: list[str] = [],
+                    imported: bool = True) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
 
         all_members = get_all_members(obj)
         for name, value in all_members.items():
@@ -312,7 +296,7 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                             public.append(name)
         return public, items
 
-    def get_module_attrs(members: Any) -> Tuple[List[str], List[str]]:
+    def get_module_attrs(members: Any) -> tuple[list[str], list[str]]:
         """Find module attributes with docstrings."""
         attrs, public = [], []
         try:
@@ -327,9 +311,17 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             pass    # give up if ModuleAnalyzer fails to parse code
         return public, attrs
 
-    def get_modules(obj: Any) -> Tuple[List[str], List[str]]:
-        items: List[str] = []
+    def get_modules(
+            obj: Any,
+            skip: Sequence[str],
+            public_members: Sequence[str] | None = None) -> tuple[list[str], list[str]]:
+        items: list[str] = []
+        public: list[str] = []
         for _, modname, _ispkg in pkgutil.iter_modules(obj.__path__):
+
+            if modname in skip:
+                # module was overwritten in __init__.py, so not accessible
+                continue
             fullname = name + '.' + modname
             try:
                 module = import_module(fullname)
@@ -339,15 +331,24 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
                 pass
 
             items.append(fullname)
-        public = [x for x in items if not x.split('.')[-1].startswith('_')]
+            if public_members is not None:
+                if modname in public_members:
+                    public.append(fullname)
+            else:
+                if not modname.startswith('_'):
+                    public.append(fullname)
         return public, items
 
-    ns: Dict[str, Any] = {}
+    ns: dict[str, Any] = {}
     ns.update(context)
 
     if doc.objtype == 'module':
         scanner = ModuleScanner(app, obj)
         ns['members'] = scanner.scan(imported_members)
+
+        respect_module_all = not app.config.autosummary_ignore_module_all
+        imported_members = imported_members or ('__all__' in dir(obj) and respect_module_all)
+
         ns['functions'], ns['all_functions'] = \
             get_members(obj, {'function'}, imported=imported_members)
         ns['classes'], ns['all_classes'] = \
@@ -358,7 +359,36 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
             get_module_attrs(ns['members'])
         ispackage = hasattr(obj, '__path__')
         if ispackage and recursive:
-            ns['modules'], ns['all_modules'] = get_modules(obj)
+            # Use members that are not modules as skip list, because it would then mean
+            # that module was overwritten in the package namespace
+            skip = (
+                ns["all_functions"]
+                + ns["all_classes"]
+                + ns["all_exceptions"]
+                + ns["all_attributes"]
+            )
+
+            # If respect_module_all and module has a __all__ attribute, first get
+            # modules that were explicitly imported. Next, find the rest with the
+            # get_modules method, but only put in "public" modules that are in the
+            # __all__ list
+            #
+            # Otherwise, use get_modules method normally
+            if respect_module_all and '__all__' in dir(obj):
+                imported_modules, all_imported_modules = \
+                    get_members(obj, {'module'}, imported=True)
+                skip += all_imported_modules
+                imported_modules = [name + '.' + modname for modname in imported_modules]
+                all_imported_modules = \
+                    [name + '.' + modname for modname in all_imported_modules]
+                public_members = getall(obj)
+            else:
+                imported_modules, all_imported_modules = [], []
+                public_members = None
+
+            modules, all_modules = get_modules(obj, skip=skip, public_members=public_members)
+            ns['modules'] = imported_modules + modules
+            ns["all_modules"] = all_imported_modules + all_modules
     elif doc.objtype == 'class':
         ns['members'] = dir(obj)
         ns['inherited_members'] = \
@@ -393,21 +423,11 @@ def generate_autosummary_content(name: str, obj: Any, parent: Any,
         return template.render(doc.objtype, ns)
 
 
-def generate_autosummary_docs(sources: List[str], output_dir: str = None,
-                              suffix: str = '.rst', base_path: str = None,
-                              builder: Builder = None, template_dir: str = None,
+def generate_autosummary_docs(sources: list[str], output_dir: str | None = None,
+                              suffix: str = '.rst', base_path: str | None = None,
                               imported_members: bool = False, app: Any = None,
                               overwrite: bool = True, encoding: str = 'utf-8') -> None:
-
-    if builder:
-        warnings.warn('builder argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    if template_dir:
-        warnings.warn('template_dir argument for generate_autosummary_docs() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
-    showed_sources = list(sorted(sources))
+    showed_sources = sorted(sources)
     if len(showed_sources) > 20:
         showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:]
     logger.info(__('[autosummary] generating autosummary for: %s') %
@@ -443,7 +463,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
         ensuredir(path)
 
         try:
-            name, obj, parent, modname = import_by_name(entry.name, grouped_exception=True)
+            name, obj, parent, modname = import_by_name(entry.name)
             qualname = name.replace(modname + ".", "")
         except ImportExceptionGroup as exc:
             try:
@@ -452,16 +472,16 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
                 qualname = name.replace(modname + ".", "")
             except ImportError as exc2:
                 if exc2.__cause__:
-                    exceptions: List[BaseException] = exc.exceptions + [exc2.__cause__]
+                    exceptions: list[BaseException] = exc.exceptions + [exc2.__cause__]
                 else:
                     exceptions = exc.exceptions + [exc2]
 
-                errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exceptions))
+                errors = list({f"* {type(e).__name__}: {e}" for e in exceptions})
                 logger.warning(__('[autosummary] failed to import %s.\nPossible hints:\n%s'),
                                entry.name, '\n'.join(errors))
                 continue
 
-        context: Dict[str, Any] = {}
+        context: dict[str, Any] = {}
         if app:
             context.update(app.config.autosummary_context)
 
@@ -533,7 +553,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
 
             if content == old_content:
                 continue
-            elif overwrite:  # content has changed
+            if overwrite:  # content has changed
                 with open(filename, 'w', encoding=encoding) as f:
                     f.write(content)
                 new_files.append(filename)
@@ -546,19 +566,18 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     if new_files:
         generate_autosummary_docs(new_files, output_dir=output_dir,
                                   suffix=suffix, base_path=base_path,
-                                  builder=builder, template_dir=template_dir,
                                   imported_members=imported_members, app=app,
                                   overwrite=overwrite)
 
 
 # -- Finding documented entries in files ---------------------------------------
 
-def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
+def find_autosummary_in_files(filenames: list[str]) -> list[AutosummaryEntry]:
     """Find out what items are documented in source/*.rst.
 
     See `find_autosummary_in_lines`.
     """
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
     for filename in filenames:
         with open(filename, encoding='utf-8', errors='ignore') as f:
             lines = f.read().splitlines()
@@ -566,33 +585,31 @@ def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]:
     return documented
 
 
-def find_autosummary_in_docstring(name: str, module: str = None, filename: str = None
-                                  ) -> List[AutosummaryEntry]:
+def find_autosummary_in_docstring(
+    name: str, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items are documented in the given object's docstring.
 
     See `find_autosummary_in_lines`.
     """
-    if module:
-        warnings.warn('module argument for find_autosummary_in_docstring() is deprecated.',
-                      RemovedInSphinx50Warning, stacklevel=2)
-
     try:
-        real_name, obj, parent, modname = import_by_name(name, grouped_exception=True)
+        real_name, obj, parent, modname = import_by_name(name)
         lines = pydoc.getdoc(obj).splitlines()
         return find_autosummary_in_lines(lines, module=name, filename=filename)
     except AttributeError:
         pass
     except ImportExceptionGroup as exc:
-        errors = list(set("* %s: %s" % (type(e).__name__, e) for e in exc.exceptions))
-        print('Failed to import %s.\nPossible hints:\n%s' % (name, '\n'.join(errors)))
+        errors = '\n'.join({f"* {type(e).__name__}: {e}" for e in exc.exceptions})
+        print(f'Failed to import {name}.\nPossible hints:\n{errors}')
     except SystemExit:
         print("Failed to import '%s'; the module executes module level "
               "statement and it might call sys.exit()." % name)
     return []
 
 
-def find_autosummary_in_lines(lines: List[str], module: str = None, filename: str = None
-                              ) -> List[AutosummaryEntry]:
+def find_autosummary_in_lines(
+    lines: list[str], module: str | None = None, filename: str | None = None,
+) -> list[AutosummaryEntry]:
     """Find out what items appear in autosummary:: directives in the
     given lines.
 
@@ -613,10 +630,10 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
     toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$')
     template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$')
 
-    documented: List[AutosummaryEntry] = []
+    documented: list[AutosummaryEntry] = []
 
     recursive = False
-    toctree: str = None
+    toctree: str | None = None
     template = None
     current_module = module
     in_autosummary = False
@@ -652,7 +669,7 @@ def find_autosummary_in_lines(lines: List[str], module: str = None, filename: st
                     name = name[1:]
                 if current_module and \
                    not name.startswith(current_module + '.'):
-                    name = "%s.%s" % (current_module, name)
+                    name = f"{current_module}.{name}"
                 documented.append(AutosummaryEntry(name, toctree, template, recursive))
                 continue
 
@@ -732,12 +749,11 @@ The format of the autosummary directive is documented in the
     return parser
 
 
-def main(argv: List[str] = sys.argv[1:]) -> None:
-    sphinx.locale.setlocale(locale.LC_ALL, '')
-    sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
-    translator, _ = sphinx.locale.init([], None)
+def main(argv: list[str] = sys.argv[1:]) -> None:
+    locale.setlocale(locale.LC_ALL, '')
+    sphinx.locale.init_console()
 
-    app = DummyApplication(translator)
+    app = DummyApplication(sphinx.locale.get_translator())
     logging.setup(app, sys.stdout, sys.stderr)  # type: ignore
     setup_documenters(app)
     args = get_parser().parse_args(argv)
diff --git a/docs/mindspore/_ext/overwriteobjectiondirective.txt b/docs/mindspore/_ext/overwriteobjectiondirective.txt
index 2088e9f22a6a82ffb26935a9f8de8306646145f7..761d35fb5c36344fab630d3b5abfb58e81dae06f 100644
--- a/docs/mindspore/_ext/overwriteobjectiondirective.txt
+++ b/docs/mindspore/_ext/overwriteobjectiondirective.txt
@@ -1,17 +1,11 @@
-"""
-    sphinx.directives
-    ~~~~~~~~~~~~~~~~~
+"""Handlers for additional ReST directives."""
 
-    Handlers for additional ReST directives.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import re
 import inspect
 import importlib
-from typing import TYPE_CHECKING, Any, Dict, Generic, List, Tuple, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Generic, List, TypeVar, cast
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -19,12 +13,11 @@ from docutils.parsers.rst import directives, roles
 
 from sphinx import addnodes
 from sphinx.addnodes import desc_signature
-from sphinx.deprecation import RemovedInSphinx50Warning, deprecated_alias
 from sphinx.util import docutils, logging
 from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.typing import OptionSpec
-from sphinx.environment.collectors.toctree import N
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
@@ -34,11 +27,11 @@ if TYPE_CHECKING:
 nl_escape_re = re.compile(r'\\\n')
 strip_backslash_re = re.compile(r'\\(.)')
 
-logger = logging.getLogger(__name__)
+ObjDescT = TypeVar('ObjDescT')
 
-# T = TypeVar('T')
+logger = logging.getLogger(__name__)
 
-def optional_int(argument: str) -> int:
+def optional_int(argument: str) -> int | None:
     """
     Check for an integer argument or None value; raise ``ValueError`` if not.
     """
@@ -122,7 +115,7 @@ def get_platforms(name: str):
     except:
         return []
 
-class ObjectDescription(SphinxDirective, Generic[N]):
+class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     """
     Directive to describe a class, function or similar object.  Not used
     directly, but subclassed (in domain-specific directives) to add custom
@@ -135,18 +128,20 @@ class ObjectDescription(SphinxDirective, Generic[N]):
     final_argument_whitespace = True
     option_spec: OptionSpec = {
         'noindex': directives.flag,
-    }  # type: Dict[str, DirectiveOption]
+        'noindexentry': directives.flag,
+        'nocontentsentry': directives.flag,
+    }
 
     # types of doc fields that this directive handles, see sphinx.util.docfields
-    doc_field_types: List[Field] = []
-    domain: str = None
-    objtype: str = None
-    indexnode: addnodes.index = None
+    doc_field_types: list[Field] = []
+    domain: str | None = None
+    objtype: str  # set when `run` method is called
+    indexnode: addnodes.index
 
     # Warning: this might be removed in future version. Don't touch this from extensions.
-    _doc_field_type_map: Dict[str, Tuple[Field, bool]] = {}
+    _doc_field_type_map: dict[str, tuple[Field, bool]] = {}
 
-    def get_field_type_map(self) -> Dict[str, Tuple[Field, bool]]:
+    def get_field_type_map(self) -> dict[str, tuple[Field, bool]]:
         if self._doc_field_type_map == {}:
             self._doc_field_type_map = {}
             for field in self.doc_field_types:
@@ -160,12 +155,10 @@ class ObjectDescription(SphinxDirective, Generic[N]):
 
         return self._doc_field_type_map
 
-    def get_signatures(self) -> List[str]:
+    def get_signatures(self) -> list[str]:
         """
         Retrieve the signatures to document from the directive arguments.  By
         default, signatures are given as arguments, one per line.
-
-        Backslash-escaping of newlines is supported.
         """
         lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
         if self.config.strip_signature_backslash:
@@ -174,7 +167,7 @@ class ObjectDescription(SphinxDirective, Generic[N]):
         else:
             return [line.strip() for line in lines]
 
-    def handle_signature(self, sig: str, signode: desc_signature):
+    def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
         """
         Parse the signature *sig* into individual nodes and append them to
         *signode*. If ValueError is raised, parsing is aborted and the whole
@@ -186,7 +179,7 @@ class ObjectDescription(SphinxDirective, Generic[N]):
         """
         raise ValueError
 
-    def add_target_and_index(self, name, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -217,6 +210,44 @@ class ObjectDescription(SphinxDirective, Generic[N]):
         """
         pass
 
+    def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
+        """
+        Returns a tuple of strings, one entry for each part of the object's
+        hierarchy (e.g. ``('module', 'submodule', 'Class', 'method')``). The
+        returned tuple is used to properly nest children within parents in the
+        table of contents, and can also be used within the
+        :py:meth:`_toc_entry_name` method.
+
+        This method must not be used outwith table of contents generation.
+        """
+        return ()
+
+    def _toc_entry_name(self, sig_node: desc_signature) -> str:
+        """
+        Returns the text of the table of contents entry for the object.
+
+        This function is called once, in :py:meth:`run`, to set the name for the
+        table of contents entry (a special attribute ``_toc_name`` is set on the
+        object node, later used in
+        ``environment.collectors.toctree.TocTreeCollector.process_doc().build_toc()``
+        when the table of contents entries are collected).
+
+        To support table of contents entries for their objects, domains must
+        override this method, also respecting the configuration setting
+        ``toc_object_entries_show_parents``. Domains must also override
+        :py:meth:`_object_hierarchy_parts`, with one (string) entry for each part of the
+        object's hierarchy. The result of this method is set on the signature
+        node, and can be accessed as ``sig_node['_toc_parts']`` for use within
+        this method. The resulting tuple is also used to properly nest children
+        within parents in the table of contents.
+
+        An example implementations of this method is within the python domain
+        (:meth:`!PyObject._toc_entry_name`). The python domain sets the
+        ``_toc_parts`` attribute within the :py:meth:`handle_signature()`
+        method.
+        """
+        return ''
+
     def check_class_end(self, content):
         for i in content:
             if not i.startswith('.. include::') and i != "\n" and i != "":
@@ -229,7 +260,7 @@ class ObjectDescription(SphinxDirective, Generic[N]):
             ls.append((rst_file, start_num+i))
         return ls
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         """
         Main directive entry function, called by docutils upon encountering the
         directive.
@@ -255,15 +286,28 @@ class ObjectDescription(SphinxDirective, Generic[N]):
 
         node = addnodes.desc()
         node.document = self.state.document
+        source, line = self.get_source_info()
+        # If any options were specified to the directive,
+        # self.state.document.current_line will at this point be set to
+        # None.  To ensure nodes created as part of the signature have a line
+        # number set, set the document's line number correctly.
+        #
+        # Note that we need to subtract one from the line number since
+        # note_source uses 0-based line numbers.
+        if line is not None:
+            line -= 1
+        self.state.document.note_source(source, line)
         node['domain'] = self.domain
         # 'desctype' is a backwards compatible attribute
         node['objtype'] = node['desctype'] = self.objtype
         node['noindex'] = noindex = ('noindex' in self.options)
+        node['noindexentry'] = ('noindexentry' in self.options)
+        node['nocontentsentry'] = ('nocontentsentry' in self.options)
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
 
-        self.names = []  # type: List[Any]
+        self.names: list[ObjDescT] = []
         signatures = self.get_signatures()
         for sig in signatures:
             # add a signature node for each signature in the current unit
@@ -281,6 +325,15 @@ class ObjectDescription(SphinxDirective, Generic[N]):
                 signode.clear()
                 signode += addnodes.desc_name(sig, sig)
                 continue  # we don't want an index entry here
+            finally:
+                # Private attributes for ToC generation. Will be modified or removed
+                # without notice.
+                if self.env.app.config.toc_object_entries:
+                    signode['_toc_parts'] = self._object_hierarchy_parts(signode)
+                    signode['_toc_name'] = self._toc_entry_name(signode)
+                else:
+                    signode['_toc_parts'] = ()
+                    signode['_toc_name'] = ''
             if name not in self.names:
                 self.names.append(name)
                 if not noindex:
@@ -290,6 +343,7 @@ class ObjectDescription(SphinxDirective, Generic[N]):
 
         contentnode = addnodes.desc_content()
         node.append(contentnode)
+
         if self.names:
             # needed for association of version{added,changed} directives
             self.env.temp_data['object'] = self.names[0]
@@ -434,7 +488,7 @@ class ObjectDescription(SphinxDirective, Generic[N]):
             self.content.items.extend(self.extend_items(self.content.items[0][0], self.content.items[-1][1], len(extra)))
         except IndexError:
             logger.warning(f'{self.names[0][0]} has error format.')
-        self.state.nested_parse(self.content, self.content_offset, contentnode)
+        nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
         self.transform_content(contentnode)
         self.env.app.emit('object-description-transform',
                           self.domain, self.objtype, contentnode)
@@ -452,14 +506,14 @@ class DefaultRole(SphinxDirective):
     optional_arguments = 1
     final_argument_whitespace = False
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         if not self.arguments:
             docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
         role, messages = roles.role(role_name, self.state_machine.language,
                                     self.lineno, self.state.reporter)
-        if role:
+        if role:  # type: ignore[truthy-function]
             docutils.register_role('', role)
             self.env.temp_data['default_role'] = role_name
         else:
@@ -483,7 +537,7 @@ class DefaultDomain(SphinxDirective):
     final_argument_whitespace = False
     option_spec: OptionSpec = {}
 
-    def run(self) -> List[Node]:
+    def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()
         # if domain_name not in env.domains:
         #     # try searching by label
@@ -494,7 +548,8 @@ class DefaultDomain(SphinxDirective):
         self.env.temp_data['default_domain'] = self.env.domains.get(domain_name)
         return []
 
-def setup(app: "Sphinx") -> Dict[str, Any]:
+
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value("strip_signature_backslash", False, 'env')
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)
diff --git a/docs/mindspore/_ext/overwriteviewcode.txt b/docs/mindspore/_ext/overwriteviewcode.txt
index 6b67087770dc200552aed4db09465a7663d151de..98374badbfd15db080d35c56025eafeb895faae1 100644
--- a/docs/mindspore/_ext/overwriteviewcode.txt
+++ b/docs/mindspore/_ext/overwriteviewcode.txt
@@ -1,18 +1,11 @@
-"""
-    sphinx.ext.viewcode
-    ~~~~~~~~~~~~~~~~~~~
+"""Add links to module code in Python object descriptions."""
 
-    Add links to module code in Python object descriptions.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import posixpath
 import traceback
-import warnings
 from os import path
-from typing import Any, Dict, Generator, Iterable, Optional, Set, Tuple, cast
+from typing import Any, Generator, Iterable, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
@@ -22,12 +15,12 @@ from sphinx import addnodes
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import get_full_modname, logging, status_iterator
+from sphinx.util import get_full_modname, logging
+from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
 
 
@@ -46,13 +39,13 @@ class viewcode_anchor(Element):
     """
 
 
-def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str]:
+def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> str | None:
     try:
         return get_full_modname(modname, attribute)
     except AttributeError:
         # sphinx.ext.viewcode can't follow class instance attribute
         # then AttributeError logging output only verbose mode.
-        logger.verbose('Didn\'t find %s in %s', attribute, modname)
+        logger.verbose("Didn't find %s in %s", attribute, modname)
         return None
     except Exception as e:
         # sphinx.ext.viewcode follow python domain directives.
@@ -67,12 +60,11 @@ def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str
 def is_supported_builder(builder: Builder) -> bool:
     if builder.format != 'html':
         return False
-    elif builder.name == 'singlehtml':
+    if builder.name == 'singlehtml':
         return False
-    elif builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
+    if builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
         return False
-    else:
-        return True
+    return True
 
 
 def doctree_read(app: Sphinx, doctree: Node) -> None:
@@ -122,7 +114,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
     for objnode in list(doctree.findall(addnodes.desc)):
         if objnode.get('domain') != 'py':
             continue
-        names: Set[str] = set()
+        names: set[str] = set()
         for signode in objnode:
             if not isinstance(signode, addnodes.desc_signature):
                 continue
@@ -232,19 +224,7 @@ class ViewcodeAnchorTransform(SphinxPostTransform):
             node.parent.remove(node)
 
 
-def missing_reference(app: Sphinx, env: BuildEnvironment, node: Element, contnode: Node
-                      ) -> Optional[Node]:
-    # resolve our "viewcode" reference nodes -- they need special treatment
-    if node['reftype'] == 'viewcode':
-        warnings.warn('viewcode extension is no longer use pending_xref node. '
-                      'Please update your extension.', RemovedInSphinx50Warning)
-        return make_refnode(app.builder, node['refdoc'], node['reftarget'],
-                            node['refid'], contnode)
-
-    return None
-
-
-def get_module_filename(app: Sphinx, modname: str) -> Optional[str]:
+def get_module_filename(app: Sphinx, modname: str) -> str | None:
     """Get module filename for *modname*."""
     source_info = app.emit_firstresult('viewcode-find-source', modname)
     if source_info:
@@ -272,13 +252,13 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
         if path.getmtime(module_filename) <= path.getmtime(page_filename):
             # generation is not needed if the HTML page is newer than module file.
             return False
-    except IOError:
+    except OSError:
         pass
 
     return True
 
 
-def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], None, None]:
+def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], None, None]:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
         return
@@ -303,7 +283,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
         # construct a page name for the highlighted source
         pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))
         # highlight the source using the builder's highlighter
-        if env.config.highlight_language in ('python3', 'default', 'none'):
+        if env.config.highlight_language in {'default', 'none'}:
             lexer = env.config.highlight_language
         else:
             lexer = 'python'
@@ -376,10 +356,9 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
                 stack.pop()
                 html.append('</ul>')
             stack.append(modname + '.')
-        html.append('<li><a href="%s">%s</a></li>\n' % (
-            urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
-                  posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))),
-            modname))
+        relative_uri = urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
+                             posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/')))
+        html.append(f'<li><a href="{relative_uri}">{modname}</a></li>\n')
     html.append('</ul>' * (len(stack) - 1))
     context = {
         'title': _('Overview: module code'),
@@ -390,7 +369,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
     yield (posixpath.join(OUTPUT_DIRNAME, 'index'), context, 'page.html')
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('viewcode_import', None, False)
     app.add_config_value('viewcode_enable_epub', False, False)
     app.add_config_value('viewcode_follow_imported_members', True, False)
@@ -398,7 +377,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect('env-merge-info', env_merge_info)
     app.connect('env-purge-doc', env_purge_doc)
     app.connect('html-collect-pages', collect_pages)
-    app.connect('missing-reference', missing_reference)
     # app.add_config_value('viewcode_include_modules', [], 'env')
     # app.add_config_value('viewcode_exclude_modules', [], 'env')
     app.add_event('viewcode-find-source')
@@ -407,5 +385,5 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     return {
         'version': sphinx.__display_version__,
         'env_version': 1,
-        'parallel_read_safe': True
+        'parallel_read_safe': True,
     }
diff --git a/docs/mindspore/_ext/overwriteviewcode_en.txt b/docs/mindspore/_ext/overwriteviewcode_en.txt
index a61bcece86be0ea42a8bcd707a3d7d9d42b4933b..48b945d415bf84d93b6ddc4a47ee22a8305b7b81 100644
--- a/docs/mindspore/_ext/overwriteviewcode_en.txt
+++ b/docs/mindspore/_ext/overwriteviewcode_en.txt
@@ -1,18 +1,11 @@
-"""
-    sphinx.ext.viewcode
-    ~~~~~~~~~~~~~~~~~~~
+"""Add links to module code in Python object descriptions."""
 
-    Add links to module code in Python object descriptions.
-
-    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
+from __future__ import annotations
 
 import posixpath
 import traceback
-import warnings
 from os import path
-from typing import Any, Dict, Generator, Iterable, Optional, Set, Tuple, cast
+from typing import Any, Generator, Iterable, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
@@ -22,12 +15,12 @@ from sphinx import addnodes
 from sphinx.application import Sphinx
 from sphinx.builders import Builder
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx50Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.transforms.post_transforms import SphinxPostTransform
-from sphinx.util import get_full_modname, logging, status_iterator
+from sphinx.util import get_full_modname, logging
+from sphinx.util.display import status_iterator
 from sphinx.util.nodes import make_refnode
 
 logger = logging.getLogger(__name__)
@@ -45,13 +38,13 @@ class viewcode_anchor(Element):
     """
 
 
-def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str]:
+def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> str | None:
     try:
         return get_full_modname(modname, attribute)
     except AttributeError:
         # sphinx.ext.viewcode can't follow class instance attribute
         # then AttributeError logging output only verbose mode.
-        logger.verbose('Didn\'t find %s in %s', attribute, modname)
+        logger.verbose("Didn't find %s in %s", attribute, modname)
         return None
     except Exception as e:
         # sphinx.ext.viewcode follow python domain directives.
@@ -66,12 +59,11 @@ def _get_full_modname(app: Sphinx, modname: str, attribute: str) -> Optional[str
 def is_supported_builder(builder: Builder) -> bool:
     if builder.format != 'html':
         return False
-    elif builder.name == 'singlehtml':
+    if builder.name == 'singlehtml':
         return False
-    elif builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
+    if builder.name.startswith('epub') and not builder.config.viewcode_enable_epub:
         return False
-    else:
-        return True
+    return True
 
 
 def doctree_read(app: Sphinx, doctree: Node) -> None:
@@ -121,7 +113,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
     for objnode in list(doctree.findall(addnodes.desc)):
         if objnode.get('domain') != 'py':
             continue
-        names: Set[str] = set()
+        names: set[str] = set()
         for signode in objnode:
             if not isinstance(signode, addnodes.desc_signature):
                 continue
@@ -216,19 +208,7 @@ class ViewcodeAnchorTransform(SphinxPostTransform):
             node.parent.remove(node)
 
 
-def missing_reference(app: Sphinx, env: BuildEnvironment, node: Element, contnode: Node
-                      ) -> Optional[Node]:
-    # resolve our "viewcode" reference nodes -- they need special treatment
-    if node['reftype'] == 'viewcode':
-        warnings.warn('viewcode extension is no longer use pending_xref node. '
-                      'Please update your extension.', RemovedInSphinx50Warning)
-        return make_refnode(app.builder, node['refdoc'], node['reftarget'],
-                            node['refid'], contnode)
-
-    return None
-
-
-def get_module_filename(app: Sphinx, modname: str) -> Optional[str]:
+def get_module_filename(app: Sphinx, modname: str) -> str | None:
     """Get module filename for *modname*."""
     source_info = app.emit_firstresult('viewcode-find-source', modname)
     if source_info:
@@ -256,13 +236,13 @@ def should_generate_module_page(app: Sphinx, modname: str) -> bool:
         if path.getmtime(module_filename) <= path.getmtime(page_filename):
             # generation is not needed if the HTML page is newer than module file.
             return False
-    except IOError:
+    except OSError:
         pass
 
     return True
 
 
-def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], None, None]:
+def collect_pages(app: Sphinx) -> Generator[tuple[str, dict[str, Any], str], None, None]:
     env = app.builder.env
     if not hasattr(env, '_viewcode_modules'):
         return
@@ -287,7 +267,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
         # construct a page name for the highlighted source
         pagename = posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))
         # highlight the source using the builder's highlighter
-        if env.config.highlight_language in ('python3', 'default', 'none'):
+        if env.config.highlight_language in {'default', 'none'}:
             lexer = env.config.highlight_language
         else:
             lexer = 'python'
@@ -360,10 +340,9 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
                 stack.pop()
                 html.append('</ul>')
             stack.append(modname + '.')
-        html.append('<li><a href="%s">%s</a></li>\n' % (
-            urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
-                  posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/'))),
-            modname))
+        relative_uri = urito(posixpath.join(OUTPUT_DIRNAME, 'index'),
+                             posixpath.join(OUTPUT_DIRNAME, modname.replace('.', '/')))
+        html.append(f'<li><a href="{relative_uri}">{modname}</a></li>\n')
     html.append('</ul>' * (len(stack) - 1))
     context = {
         'title': _('Overview: module code'),
@@ -374,7 +353,7 @@ def collect_pages(app: Sphinx) -> Generator[Tuple[str, Dict[str, Any], str], Non
     yield (posixpath.join(OUTPUT_DIRNAME, 'index'), context, 'page.html')
 
 
-def setup(app: Sphinx) -> Dict[str, Any]:
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_config_value('viewcode_import', None, False)
     app.add_config_value('viewcode_enable_epub', False, False)
     app.add_config_value('viewcode_follow_imported_members', True, False)
@@ -382,7 +361,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect('env-merge-info', env_merge_info)
     app.connect('env-purge-doc', env_purge_doc)
     app.connect('html-collect-pages', collect_pages)
-    app.connect('missing-reference', missing_reference)
     # app.add_config_value('viewcode_include_modules', [], 'env')
     # app.add_config_value('viewcode_exclude_modules', [], 'env')
     app.add_event('viewcode-find-source')
@@ -391,5 +369,5 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     return {
         'version': sphinx.__display_version__,
         'env_version': 1,
-        'parallel_read_safe': True
+        'parallel_read_safe': True,
     }
diff --git a/docs/mindspore/requirements.txt b/docs/mindspore/requirements.txt
index 15a923bbf3f3adce685f577d3acaa91f8a841afb..6262c316906e36c210139b49b924e6aeeb787971 100644
--- a/docs/mindspore/requirements.txt
+++ b/docs/mindspore/requirements.txt
@@ -1,7 +1,7 @@
-sphinx == 4.4.0
-docutils == 0.17.1
-myst-parser == 0.18.1
-sphinx_rtd_theme == 1.0.0
+sphinx == 7.0.1
+docutils == 0.20.1
+myst-parser == 2.0.0
+sphinx_rtd_theme == 3.0.0
 numpy
 nbsphinx == 0.8.11
 IPython
diff --git a/docs/mindspore/source_en/conf.py b/docs/mindspore/source_en/conf.py
index d0187a1d0a36c638849ba517c820ab47de0fc1be..c96187587811ff6db6ae1cf33073818f5912b78a 100644
--- a/docs/mindspore/source_en/conf.py
+++ b/docs/mindspore/source_en/conf.py
@@ -27,14 +27,11 @@ from docutils.writers import _html_base
 
 with open(_html_base.__file__, "r", encoding="utf-8") as f:
     code_str = f.read()
-    old_str = '''        if self.is_compactable(node):
-            classes.append('simple')'''
-    new_str = '''        if classes == []:
-            classes.append('simple')'''
+    old_str = "classes = ['simple'] if self.is_compactable(node) else []"
+    new_str = "classes = ['simple']"
     code_str = code_str.replace(old_str, new_str)
     exec(code_str, _html_base.__dict__)
 
-
 # Fix mathjax tags
 from sphinx.ext import mathjax as sphinx_mathjax
 
@@ -263,8 +260,8 @@ try:
 except:
     pass
 
-sys.path.append(os.path.abspath('../../../resource/search'))
-import search_code
+# sys.path.append(os.path.abspath('../../../resource/search'))
+# import search_code
 
 # Copy source files of en python api from mindspore repository.
 copy_path = 'docs/api/api_python_en'
@@ -324,7 +321,7 @@ def mint_interface_name():
 try:
     primitive_list = ops_interface_name()
 except:
-    pass
+    primitive_list = []
 
 mint_sum = mint_interface_name()
 
diff --git a/docs/mindspore/source_zh_cn/conf.py b/docs/mindspore/source_zh_cn/conf.py
index 94f7fc5cb25ac8cc40c6e0de8d3b35549335d57c..c86fd1a71dcb2b8ef1863df633a1e78bd2156ae0 100644
--- a/docs/mindspore/source_zh_cn/conf.py
+++ b/docs/mindspore/source_zh_cn/conf.py
@@ -26,10 +26,8 @@ from docutils.writers import _html_base
 
 with open(_html_base.__file__, "r", encoding="utf-8") as f:
     code_str = f.read()
-    old_str = '''        if self.is_compactable(node):
-            classes.append('simple')'''
-    new_str = '''        if classes == []:
-            classes.append('simple')'''
+    old_str = "classes = ['simple'] if self.is_compactable(node) else []"
+    new_str = "classes = ['simple']"
     code_str = code_str.replace(old_str, new_str)
     exec(code_str, _html_base.__dict__)
 
@@ -229,7 +227,7 @@ with open(gfile_abs_path, "r", encoding="utf8") as f:
 
 
 sys.path.append(os.path.abspath('../../../resource/search'))
-import search_code
+# import search_code
 
 # Copy source files of chinese python api from mindspore repository.
 from sphinx.util import logging
@@ -557,8 +555,11 @@ except Exception as e:
     print(e)
 
 primitive_list = ops_interface_name()
+# primitive_list = []
 
 mint_sum = mint_interface_name()
+# mint_sum = []
+
 
 try:
     nn_interface_name()
diff --git a/resource/_static/layout.html b/resource/_static/layout.html
index a49fd97a4f6a7bd42b47c1cd35e6f3c7b0f8559b..c46b4faa6d98dccb787849d478fe1c2b07adbdea 100644
--- a/resource/_static/layout.html
+++ b/resource/_static/layout.html
@@ -7,16 +7,18 @@
   {%- set titlesuffix = "" %}
 {%- endif %}
 {%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %}
-{%- set sphinx_writer = 'writer-html5' if html5_doctype else 'writer-html4' -%}
 
 {# Build sphinx_version_info tuple from sphinx_version string in pure Jinja #}
-{%- set (_ver_major, _ver_minor, _ver_bugfix) = sphinx_version.split('.') | map('int') -%}
-{%- set sphinx_version_info = (_ver_major, _ver_minor, _ver_bugfix) -%}
+{%- set (_ver_major, _ver_minor) = (sphinx_version.split('.') | list)[:2] | map('int') -%}
+{%- set sphinx_version_info = (_ver_major, _ver_minor, -1) -%}
 
 <!DOCTYPE html>
-<html class="{{ sphinx_writer }}" lang="{{ lang_attr }}" >
+<html class="writer-html5" lang="{{ lang_attr }}"{% if sphinx_version_info >= (7, 2) %} data-content_root="{{ content_root }}"{% endif %}>
 <head>
   <meta charset="utf-8" />
+  {%- if READTHEDOCS and not embedded %}
+  <meta name="readthedocs-addons-api-version" content="1">
+  {%- endif %}
   {{- metatags }}
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   {%- block htmltitle %}
@@ -25,34 +27,31 @@
 
   <script>;(()=>{const e=localStorage.getItem("ms-theme"),t=window.matchMedia("(prefers-color-scheme: dark)").matches;(e?"dark"===e:t)&&document.documentElement.setAttribute("data-o-theme","dark")})();</script>
   {#- CSS #}
-  {%- if sphinx_version_info < (4, 0) -%}
-    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
-    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
-  {%- endif %}
-
-  {%- for css in css_files %}
-    {%- if css|attr("rel") %}
-      <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
-    {%- elif 'css/theme.css' not in css and  '/pygments.css' not in css %}
-      <link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
+  {%- for css_file in css_files %}
+    {%- if css_file|attr("rel") %}
+      <link rel="{{ css_file.rel }}" href="{{ pathto(css_file.filename, 1) }}" type="text/css"{% if css_file.title is not none %} title="{{ css.title }}"{% endif %} />
+    {%- elif 'css/theme.css' not in css_file and  '/pygments.css' not in css_file %}
+      <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
     {%- endif %}
   {%- endfor %}
 
-  {%- for cssfile in extra_css_files %}
-    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+  {#
+      "extra_css_files" is an undocumented Read the Docs theme specific option.
+      There is no need to check for ``|attr("filename")`` here because it's always a string.
+      Note that this option should be removed in favor of regular ``html_css_files``:
+      https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files
+  #}
+  {%- for css_file in extra_css_files %}
+    <link rel="stylesheet" href="{{ pathto(css_file, 1)|escape }}" type="text/css" />
   {%- endfor -%}
 
-  <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
+  <link rel="stylesheet" href="{{ pathto('_static/css/theme.css', 1) }}" type="text/css" />
   <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
 
   {#- FAVICON #}
-  {%- if favicon %}
-    {%- if sphinx_version_info < (4, 0) -%}
-    <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
-    {%- else %}
+  {%- if favicon_url %}
     <link rel="shortcut icon" href="{{ favicon_url }}"/>
-    {%- endif %}
-  {%- endif -%}
+  {%- endif %}
 
   {#- CANONICAL URL (deprecated) #}
   {%- if theme_canonical_url and not pageurl %}
@@ -67,34 +66,13 @@
   {#- JAVASCRIPTS #}
   {%- block scripts %}
   {%- if not embedded %}
-  {# XXX Sphinx 1.8.0 made this an external js-file, quick fix until we refactor the template to inherert more blocks directly from sphinx #}
-    {%- if sphinx_version_info >= (1, 8) -%}
-      {%- if sphinx_version_info < (4, 0) -%}
-      <script id="documentation_options" data-url_root="{{ url_root }}" src="{{ pathto('_static/documentation_options.js', 1) }}"></script>
-      {%- endif -%}
-      {%- for scriptfile in script_files %}
-        {%- if 'jquery.js' in scriptfile -%}
-        {{ js_tag(scriptfile) }}
-        {{ js_tag('_static/js/theme.js') }}
-        {%- else -%}
-        {{ js_tag(scriptfile) }}
-        {%- endif -%}
-      {%- endfor %}
-    {%- else %}
-      <script>
-          var DOCUMENTATION_OPTIONS = {
-              URL_ROOT:'{{ url_root }}',
-              VERSION:'{{ release|e }}',
-              LANGUAGE:'{{ language }}',
-              COLLAPSE_INDEX:false,
-              FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
-              HAS_SOURCE:  {{ has_source|lower }},
-              SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}'
-          };
-      </script>
-      {%- for scriptfile in script_files %}
-        <script src="{{ pathto(scriptfile, 1) }}"></script>
-      {%- endfor %}
+    {%- for scriptfile in script_files %}
+      {{ js_tag(scriptfile) }}
+    {%- endfor %}
+    <script src="{{ pathto('_static/js/theme.js', 1) }}"></script>
+
+    {%- if READTHEDOCS or DEBUG %}
+    <script src="{{ pathto('_static/js/versions.js', 1) }}"></script>
     {%- endif %}
 
     {#- OPENSEARCH #}
@@ -139,32 +117,22 @@
         <div class="wy-side-nav-search" {% if theme_style_nav_header_background %} style="background: {{theme_style_nav_header_background}}" {% endif %}>
           {%- block sidebartitle %}
 
-          {%- if logo and theme_logo_only %}
-            <a href="{{ pathto(master_doc) }}">
-          {%- else %}
-            <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
-          {%- endif %}
-
-          {%- if logo %}
-            {#- Not strictly valid HTML, but it's the only way to display/scale
-                it properly, without weird scripting or heaps of work
-            #}
-            {%- if sphinx_version_info < (4, 0) -%}
-            <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
-            {%- else %}
-            <img src="{{ logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
+          {# the logo helper function was removed in Sphinx 6 and deprecated since Sphinx 4 #}
+          {# the master_doc variable was renamed to root_doc in Sphinx 4 (master_doc still exists in later Sphinx versions) #}
+          {%- set _logo_url = logo_url|default(pathto('_static/' + (logo or ""), 1)) %}
+          {%- set _root_doc = root_doc|default(master_doc) %}
+          <a href="{{ pathto(_root_doc) }}"{% if not theme_logo_only %} class="icon icon-home"{% endif %}>
+            {% if not theme_logo_only %}{{ project }}{% endif %}
+            {%- if logo or logo_url %}
+              <img src="{{ _logo_url }}" class="logo" alt="{{ _('Logo') }}"/>
             {%- endif %}
-          {%- endif %}
           </a>
 
-          {%- if theme_display_version %}
-            {%- set nav_version = version %}
-            {%- if READTHEDOCS and current_version %}
-              {%- set nav_version = current_version %}
-            {%- endif %}
-            {%- if nav_version %}
-              <div class="version">
-                {{ nav_version }}
+          {%- if READTHEDOCS or DEBUG %}
+            {%- if theme_version_selector or theme_language_selector %}
+              <div class="switch-menus">
+                <div class="version-switch"></div>
+                <div class="language-switch"></div>
               </div>
             {%- endif %}
           {%- endif %}
@@ -258,5 +226,6 @@
   {%- endif %}
 
   {%- block footer %} {% endblock %}
+
 </body>
 </html>
diff --git a/resource/sphinx_ext/nodes.txt b/resource/sphinx_ext/nodes.txt
index faafc34ef0affa1e1d32368a8d51a7a68ac824a0..6b4e85bec09792a45c64624b0e3369f27c993a31 100644
--- a/resource/sphinx_ext/nodes.txt
+++ b/resource/sphinx_ext/nodes.txt
@@ -1,4 +1,4 @@
-# $Id: nodes.py 8592 2020-12-15 23:06:26Z milde $
+# $Id: nodes.py 9310 2022-12-17 12:17:32Z milde $
 # Author: David Goodger <goodger@python.org>
 # Maintainer: docutils-develop@lists.sourceforge.net
 # Copyright: This module has been placed in the public domain.
@@ -17,57 +17,27 @@ is represented by abstract base classes (`Root`, `Structural`, `Body`,
 ``isinstance(node, base_class)`` to determine the position of the node in the
 hierarchy.
 
-.. _DTD: http://docutils.sourceforge.net/docs/ref/docutils.dtd
+.. _DTD: https://docutils.sourceforge.io/docs/ref/docutils.dtd
 """
-from __future__ import print_function
-from collections import Counter
 
 __docformat__ = 'reStructuredText'
 
-import sys
-import os
+from collections import Counter
 import re
+import sys
 import warnings
 import unicodedata
+# import xml.dom.minidom as dom # -> conditional import in Node.asdom()
+#                                    and document.asdom()
 
-if sys.version_info >= (3, 0):
-    unicode = str  # noqa
-    basestring = str  # noqa
-
-class _traversal_list(list):
-    # auxiliary class to report a FutureWarning
-    done = False
-    def _warning_decorator(fun):
-        msg = ("\n   The iterable returned by Node.traverse()"
-               "\n   will become an iterator instead of a list in "
-               "Docutils > 0.16.")
-        def wrapper(self, *args, **kwargs):
-            if not self.done:
-                warnings.warn(msg, FutureWarning, stacklevel=2)
-            self.done = True
-            return fun(self, *args, **kwargs)
-        return wrapper
-
-    __add__ = _warning_decorator(list.__add__)
-    __contains__ = _warning_decorator(list.__contains__)
-    __getitem__ = _warning_decorator(list.__getitem__)
-    __reversed__ = _warning_decorator(list.__reversed__)
-    __setitem__ = _warning_decorator(list.__setitem__)
-    append = _warning_decorator(list.append)
-    count = _warning_decorator(list.count)
-    extend = _warning_decorator(list.extend)
-    index = _warning_decorator(list.index)
-    insert = _warning_decorator(list.insert)
-    pop = _warning_decorator(list.pop)
-    reverse = _warning_decorator(list.reverse)
+# import docutils.transforms # -> conditional import in document.__init__()
 
 
 # ==============================
 #  Functional Node Base Classes
 # ==============================
 
-class Node(object):
-
+class Node:
     """Abstract base class of nodes in a document tree."""
 
     parent = None
@@ -83,8 +53,7 @@ class Node(object):
 
     @property
     def document(self):
-        """
-        Return the `document` node at the root of the tree containing this Node.
+        """Return the `document` root node of the tree containing this Node.
         """
         try:
             return self._document or self.parent.document
@@ -101,20 +70,10 @@ class Node(object):
         than a simple container.  Its boolean "truth" does not depend on
         having one or more subnodes in the doctree.
 
-        Use `len()` to check node length.  Use `None` to represent a boolean
-        false value.
+        Use `len()` to check node length.
         """
         return True
 
-    if sys.version_info < (3, 0):
-        __nonzero__ = __bool__
-
-    if sys.version_info < (3, 0):
-        # on 2.x, str(node) will be a byte string with Unicode
-        # characters > 255 escaped; on 3.x this is no longer necessary
-        def __str__(self):
-            return unicode(self).encode('raw_unicode_escape')
-
     def asdom(self, dom=None):
         """Return a DOM **fragment** representation of this Node."""
         if dom is None:
@@ -240,39 +199,55 @@ class Node(object):
             visitor.dispatch_departure(self)
         return stop
 
-    def _fast_traverse(self, cls):
+    def _fast_findall(self, cls):
         """Return iterator that only supports instance checks."""
         if isinstance(self, cls):
             yield self
         for child in self.children:
-            for subnode in child._fast_traverse(cls):
-                yield subnode
+            yield from child._fast_findall(cls)
 
-    def _all_traverse(self):
+    def _superfast_findall(self):
         """Return iterator that doesn't check for a condition."""
+        # This is different from ``iter(self)`` implemented via
+        # __getitem__() and __len__() in the Element subclass,
+        # which yields only the direct children.
         yield self
         for child in self.children:
-            for subnode in child._all_traverse():
-                yield subnode
+            yield from child._superfast_findall()
 
     def traverse(self, condition=None, include_self=True, descend=True,
                  siblings=False, ascend=False):
+        """Return list of nodes following `self`.
+
+        For looping, Node.findall() is faster and more memory efficient.
         """
-        Return an iterable containing
+        # traverse() may be eventually removed:
+        warnings.warn('nodes.Node.traverse() is obsoleted by Node.findall().',
+                      PendingDeprecationWarning, stacklevel=2)
+        return list(self.findall(condition, include_self, descend,
+                                 siblings, ascend))
 
-        * self (if include_self is true)
-        * all descendants in tree traversal order (if descend is true)
-        * all siblings (if siblings is true) and their descendants (if
-          also descend is true)
-        * the siblings of the parent (if ascend is true) and their
-          descendants (if also descend is true), and so on
+    def findall(self, condition=None, include_self=True, descend=True,
+                siblings=False, ascend=False):
+        """
+        Return an iterator yielding nodes following `self`:
+
+        * self (if `include_self` is true)
+        * all descendants in tree traversal order (if `descend` is true)
+        * the following siblings (if `siblings` is true) and their
+          descendants (if also `descend` is true)
+        * the following siblings of the parent (if `ascend` is true) and
+          their descendants (if also `descend` is true), and so on.
 
-        If `condition` is not None, the iterable contains only nodes
+        If `condition` is not None, the iterator yields only nodes
         for which ``condition(node)`` is true.  If `condition` is a
         node class ``cls``, it is equivalent to a function consisting
         of ``return isinstance(node, cls)``.
 
-        If ascend is true, assume siblings to be true as well.
+        If `ascend` is true, assume `siblings` to be true as well.
+
+        If the tree structure is modified during iteration, the result
+        is undefined.
 
         For example, given the following tree::
 
@@ -284,62 +259,52 @@ class Node(object):
                 <reference name="Baz" refid="baz">
                     Baz
 
-        Then list(emphasis.traverse()) equals ::
+        Then tuple(emphasis.traverse()) equals ::
 
-            [<emphasis>, <strong>, <#text: Foo>, <#text: Bar>]
+            (<emphasis>, <strong>, <#text: Foo>, <#text: Bar>)
 
-        and list(strong.traverse(ascend=True)) equals ::
+        and list(strong.traverse(ascend=True) equals ::
 
             [<strong>, <#text: Foo>, <#text: Bar>, <reference>, <#text: Baz>]
         """
-        # Although the documented API only promises an "iterable" as return
-        # value, the implementation returned a list up to v. 0.15. Some 3rd
-        # party code still relies on this (e.g. Sphinx as of 2019-09-07).
-        # Therefore, let's return a list until this is sorted out:
-        return _traversal_list(self._traverse(condition, include_self,
-                                   descend, siblings, ascend))
-
-    def _traverse(self, condition=None, include_self=True, descend=True,
-                  siblings=False, ascend=False):
-        """Return iterator over nodes following `self`. See `traverse()`."""
         if ascend:
-            siblings=True
+            siblings = True
         # Check for special argument combinations that allow using an
         # optimized version of traverse()
         if include_self and descend and not siblings:
             if condition is None:
-                for subnode in self._all_traverse():
-                    yield subnode
+                yield from self._superfast_findall()
                 return
             elif isinstance(condition, type):
-                for subnode in self._fast_traverse(condition):
-                    yield subnode
+                yield from self._fast_findall(condition)
                 return
         # Check if `condition` is a class (check for TypeType for Python
         # implementations that use only new-style classes, like PyPy).
         if isinstance(condition, type):
             node_class = condition
+
             def condition(node, node_class=node_class):
                 return isinstance(node, node_class)
 
-
         if include_self and (condition is None or condition(self)):
             yield self
         if descend and len(self.children):
             for child in self:
-                for subnode in child._traverse(condition=condition,
-                                    include_self=True, descend=True,
-                                    siblings=False, ascend=False):
-                    yield subnode
+                yield from child.findall(condition=condition,
+                                         include_self=True, descend=True,
+                                         siblings=False, ascend=False)
         if siblings or ascend:
             node = self
             while node.parent:
                 index = node.parent.index(node)
+                # extra check since Text nodes have value-equality
+                while node.parent[index] is not node:
+                    index = node.parent.index(node, index + 1)
                 for sibling in node.parent[index+1:]:
-                    for subnode in sibling._traverse(condition=condition,
-                                        include_self=True, descend=descend,
-                                        siblings=False, ascend=False):
-                        yield subnode
+                    yield from sibling.findall(
+                        condition=condition,
+                        include_self=True, descend=descend,
+                        siblings=False, ascend=False)
                 if not ascend:
                     break
                 else:
@@ -348,39 +313,40 @@ class Node(object):
     def next_node(self, condition=None, include_self=False, descend=True,
                   siblings=False, ascend=False):
         """
-        Return the first node in the iterable returned by traverse(),
+        Return the first node in the iterator returned by findall(),
         or None if the iterable is empty.
 
-        Parameter list is the same as of traverse.  Note that
-        include_self defaults to False, though.
+        Parameter list is the same as of traverse.  Note that `include_self`
+        defaults to False, though.
         """
-        node_iterator = self._traverse(condition, include_self,
-                                      descend, siblings, ascend)
         try:
-            return next(node_iterator)
+            return next(self.findall(condition, include_self,
+                                     descend, siblings, ascend))
         except StopIteration:
             return None
 
-if sys.version_info < (3, 0):
-    class reprunicode(unicode):
-        """
-        A unicode sub-class that removes the initial u from unicode's repr.
-        """
 
-        def __repr__(self):
-            return unicode.__repr__(self)[1:]
-else:
-    reprunicode = unicode
+class reprunicode(str):
+    """
+    Deprecated backwards compatibility stub. Use the standard `str` instead.
+    """
+    def __init__(self, s):
+        warnings.warn('nodes.reprunicode() is not required with Python 3'
+                      ' and will be removed in Docutils 0.21 or later.',
+                      DeprecationWarning, stacklevel=2)
+        super().__init__()
 
 
 def ensure_str(s):
     """
-    Fail-safe conversion of `unicode` to `str`.
+    Deprecated backwards compatibility stub returning `s`.
     """
-    if sys.version_info < (3, 0) and isinstance(s, unicode):
-        return s.encode('ascii', 'backslashreplace')
+    warnings.warn('nodes.ensure_str() is not required with Python 3'
+                  ' and will be removed in Docutils 0.21 or later.',
+                  DeprecationWarning, stacklevel=2)
     return s
 
+
 # definition moved here from `utils` to avoid circular import dependency
 def unescape(text, restore_backslashes=False, respect_whitespace=False):
     """
@@ -396,12 +362,14 @@ def unescape(text, restore_backslashes=False, respect_whitespace=False):
         return text
 
 
-class Text(Node, reprunicode):
+class Text(Node, str):
 
     """
     Instances are terminal nodes (leaves) containing text only; no child
     nodes or attributes.  Initialize by passing a string to the constructor.
-    Access the text itself with the `astext` method.
+
+    Access the raw (null-escaped) text with ``str(<instance>)``
+    and unescaped text with ``<instance>.astext()``.
     """
 
     tagname = '#text'
@@ -409,58 +377,46 @@ class Text(Node, reprunicode):
     children = ()
     """Text nodes have no children, and cannot have children."""
 
-    if sys.version_info > (3, 0):
-        def __new__(cls, data, rawsource=None):
-            """Prevent the rawsource argument from propagating to str."""
-            if isinstance(data, bytes):
-                raise TypeError('expecting str data, not bytes')
-            return reprunicode.__new__(cls, data)
-    else:
-        def __new__(cls, data, rawsource=None):
-            """Prevent the rawsource argument from propagating to str."""
-            return reprunicode.__new__(cls, data)
-
-    def __init__(self, data, rawsource=''):
-        self.rawsource = rawsource
-        """The raw text from which this element was constructed."""
+    def __new__(cls, data, rawsource=None):
+        """Assert that `data` is not an array of bytes
+        and warn if the deprecated `rawsource` argument is used.
+        """
+        if isinstance(data, bytes):
+            raise TypeError('expecting str data, not bytes')
+        if rawsource is not None:
+            warnings.warn('nodes.Text: initialization argument "rawsource" '
+                          'is ignored and will be removed in Docutils 2.0.',
+                          DeprecationWarning, stacklevel=2)
+        return str.__new__(cls, data)
 
     def shortrepr(self, maxlen=18):
         data = self
         if len(data) > maxlen:
             data = data[:maxlen-4] + ' ...'
-        return '<%s: %r>' % (self.tagname, reprunicode(data))
+        return '<%s: %r>' % (self.tagname, str(data))
 
     def __repr__(self):
         return self.shortrepr(maxlen=68)
 
     def _dom_node(self, domroot):
-        return domroot.createTextNode(unicode(self))
+        return domroot.createTextNode(str(self))
 
     def astext(self):
-        return reprunicode(unescape(self))
-
-    # Note about __unicode__: The implementation of __unicode__ here,
-    # and the one raising NotImplemented in the superclass Node had
-    # to be removed when changing Text to a subclass of unicode instead
-    # of UserString, since there is no way to delegate the __unicode__
-    # call to the superclass unicode:
-    # unicode itself does not have __unicode__ method to delegate to
-    # and calling unicode(self) or unicode.__new__ directly creates
-    # an infinite loop
+        return str(unescape(self))
 
     def copy(self):
-        return self.__class__(reprunicode(self), rawsource=self.rawsource)
+        return self.__class__(str(self))
 
     def deepcopy(self):
         return self.copy()
 
     def pformat(self, indent='    ', level=0):
         try:
-            if self.document.settings.detailled:
-                lines = ['%s%s' % (indent * level, '<#text>')
-                        ] + [indent*(level+1) + repr(line)
-                             for line in self.splitlines(keepends=True)]
-                return '\n'.join(lines) + '\n'
+            if self.document.settings.detailed:
+                tag = '%s%s' % (indent*level, '<#text>')
+                lines = (indent*(level+1) + repr(line)
+                         for line in self.splitlines(True))
+                return '\n'.join((tag, *lines)) + '\n'
         except AttributeError:
             pass
         indent = indent * level
@@ -474,33 +430,46 @@ class Text(Node, reprunicode):
     # taken care of by UserString.
 
     def rstrip(self, chars=None):
-        return self.__class__(reprunicode.rstrip(self, chars), self.rawsource)
+        return self.__class__(str.rstrip(self, chars))
 
     def lstrip(self, chars=None):
-        return self.__class__(reprunicode.lstrip(self, chars), self.rawsource)
+        return self.__class__(str.lstrip(self, chars))
+
 
 class Element(Node):
 
     """
     `Element` is the superclass to all specific elements.
 
-    Elements contain attributes and child nodes.  Elements emulate
-    dictionaries for attributes, indexing by attribute name (a string).  To
-    set the attribute 'att' to 'value', do::
+    Elements contain attributes and child nodes.
+    They can be described as a cross between a list and a dictionary.
+
+    Elements emulate dictionaries for external [#]_ attributes, indexing by
+    attribute name (a string). To set the attribute 'att' to 'value', do::
 
         element['att'] = 'value'
 
+    .. [#] External attributes correspond to the XML element attributes.
+       From its `Node` superclass, Element also inherits "internal"
+       class attributes that are accessed using the standard syntax, e.g.
+       ``element.parent``.
+
     There are two special attributes: 'ids' and 'names'.  Both are
-    lists of unique identifiers, and names serve as human interfaces
-    to IDs.  Names are case- and whitespace-normalized (see the
-    fully_normalize_name() function), and IDs conform to the regular
-    expression ``[a-z](-?[a-z0-9]+)*`` (see the make_id() function).
+    lists of unique identifiers: 'ids' conform to the regular expression
+    ``[a-z](-?[a-z0-9]+)*`` (see the make_id() function for rationale and
+    details). 'names' serve as user-friendly interfaces to IDs; they are
+    case- and whitespace-normalized (see the fully_normalize_name() function).
 
-    Elements also emulate lists for child nodes (element nodes and/or text
+    Elements emulate lists for child nodes (element nodes and/or text
     nodes), indexing by integer.  To get the first child node, use::
 
         element[0]
 
+    to iterate over the child nodes (without descending), use::
+
+        for child in element:
+            ...
+
     Elements may be constructed using the ``+=`` operator.  To add one new
     child node to element, do::
 
@@ -517,22 +486,22 @@ class Element(Node):
     """
 
     basic_attributes = ('ids', 'classes', 'names', 'dupnames')
-    """List attributes which are defined for every Element-derived class
+    """Tuple of attributes which are defined for every Element-derived class
     instance and can be safely transferred to a different node."""
 
     local_attributes = ('backrefs',)
-    """A list of class-specific attributes that should not be copied with the
+    """Tuple of class-specific attributes that should not be copied with the
     standard attributes when replacing a node.
 
     NOTE: Derived classes should override this value to prevent any of its
     attributes being copied by adding to the value in its parent class."""
 
     list_attributes = basic_attributes + local_attributes
-    """List attributes, automatically initialized to empty lists for
-    all nodes."""
+    """Tuple of attributes that are automatically initialized to empty lists
+    for all nodes."""
 
-    known_attributes = list_attributes + ('source', 'rawsource')
-    """List attributes that are known to the Element base class."""
+    known_attributes = list_attributes + ('source',)
+    """Tuple of attributes that are known to the Element base class."""
 
     tagname = None
     """The element generic identifier. If None, it is set as an instance
@@ -575,7 +544,7 @@ class Element(Node):
         element = domroot.createElement(self.tagname)
         for attribute, value in self.attlist():
             if isinstance(value, list):
-                value = ' '.join([serial_escape('%s' % (v,)) for v in value])
+                value = ' '.join(serial_escape('%s' % (v,)) for v in value)
             element.setAttribute(attribute, '%s' % value)
         for child in self.children:
             element.appendChild(child._dom_node(domroot))
@@ -590,28 +559,25 @@ class Element(Node):
                 break
         if self['names']:
             return '<%s "%s": %s>' % (self.__class__.__name__,
-                '; '.join([ensure_str(n) for n in self['names']]), data)
+                                      '; '.join(self['names']), data)
         else:
             return '<%s: %s>' % (self.__class__.__name__, data)
 
     def shortrepr(self):
         if self['names']:
             return '<%s "%s"...>' % (self.__class__.__name__,
-                '; '.join([ensure_str(n) for n in self['names']]))
+                                     '; '.join(self['names']))
         else:
             return '<%s...>' % self.tagname
 
-    def __unicode__(self):
+    def __str__(self):
         if self.children:
-            return u'%s%s%s' % (self.starttag(),
-                                ''.join([unicode(c) for c in self.children]),
-                                self.endtag())
+            return '%s%s%s' % (self.starttag(),
+                               ''.join(str(c) for c in self.children),
+                               self.endtag())
         else:
             return self.emptytag()
 
-    if sys.version_info >= (3, 0):
-        __str__ = __unicode__
-
     def starttag(self, quoteattr=None):
         # the optional arg is used by the docutils_xml writer
         if quoteattr is None:
@@ -625,30 +591,29 @@ class Element(Node):
                 values = [serial_escape('%s' % (v,)) for v in value]
                 value = ' '.join(values)
             else:
-                value = unicode(value)
+                value = str(value)
             value = quoteattr(value)
-            parts.append(u'%s=%s' % (name, value))
-        return u'<%s>' % u' '.join(parts)
+            parts.append('%s=%s' % (name, value))
+        return '<%s>' % ' '.join(parts)
 
     def endtag(self):
         return '</%s>' % self.tagname
 
     def emptytag(self):
-        return u'<%s/>' % u' '.join([self.tagname] +
-                                    ['%s="%s"' % (n, v)
-                                     for n, v in self.attlist()])
+        attributes = ('%s="%s"' % (n, v) for n, v in self.attlist())
+        return '<%s/>' % ' '.join((self.tagname, *attributes))
 
     def __len__(self):
         return len(self.children)
 
     def __contains__(self, key):
         # Test for both, children and attributes with operator ``in``.
-        if isinstance(key, basestring):
+        if isinstance(key, str):
             return key in self.attributes
         return key in self.children
 
     def __getitem__(self, key):
-        if isinstance(key, basestring):
+        if isinstance(key, str):
             return self.attributes[key]
         elif isinstance(key, int):
             return self.children[key]
@@ -660,7 +625,7 @@ class Element(Node):
                             'an attribute name string')
 
     def __setitem__(self, key, item):
-        if isinstance(key, basestring):
+        if isinstance(key, str):
             self.attributes[str(key)] = item
         elif isinstance(key, int):
             self.setup_child(item)
@@ -675,7 +640,7 @@ class Element(Node):
                             'an attribute name string')
 
     def __delitem__(self, key):
-        if isinstance(key, basestring):
+        if isinstance(key, str):
             del self.attributes[key]
         elif isinstance(key, int):
             del self.children[key]
@@ -702,7 +667,7 @@ class Element(Node):
 
     def astext(self):
         return self.child_text_separator.join(
-              [child.astext() for child in self.children])
+                   [child.astext() for child in self.children])
 
     def non_default_attributes(self):
         atts = {}
@@ -712,8 +677,7 @@ class Element(Node):
         return atts
 
     def attlist(self):
-        attlist = sorted(self.non_default_attributes().items())
-        return attlist
+        return sorted(self.non_default_attributes().items())
 
     def get(self, key, failobj=None):
         return self.attributes.get(key, failobj)
@@ -766,8 +730,16 @@ class Element(Node):
     def remove(self, item):
         self.children.remove(item)
 
-    def index(self, item):
-        return self.children.index(item)
+    def index(self, item, start=0, stop=sys.maxsize):
+        return self.children.index(item, start, stop)
+
+    def previous_sibling(self):
+        """Return preceding sibling node or ``None``."""
+        try:
+            i = self.parent.index(self)
+        except (AttributeError):
+            return None
+        return self.parent[i-1] if i > 0 else None
 
     def is_not_default(self, key):
         if self[key] == [] and key in self.list_attributes:
@@ -795,7 +767,7 @@ class Element(Node):
         """
         # List Concatenation
         for value in values:
-            if not value in self[attr]:
+            if value not in self[attr]:
                 self[attr].append(value)
 
     def coerce_append_attr_list(self, attr, value):
@@ -813,7 +785,7 @@ class Element(Node):
             value = [value]
         self.append_attr_list(attr, value)
 
-    def replace_attr(self, attr, value, force = True):
+    def replace_attr(self, attr, value, force=True):
         """
         If self[attr] does not exist or force is True or omitted, set
         self[attr] to value, otherwise do nothing.
@@ -822,7 +794,7 @@ class Element(Node):
         if force or self.get(attr) is None:
             self[attr] = value
 
-    def copy_attr_convert(self, attr, value, replace = True):
+    def copy_attr_convert(self, attr, value, replace=True):
         """
         If attr is an attribute of self, set self[attr] to
         [self[attr], value], otherwise set self[attr] to value.
@@ -872,8 +844,8 @@ class Element(Node):
         if self.get(attr) is not value:
             self.replace_attr(attr, value, replace)
 
-    def update_all_atts(self, dict_, update_fun = copy_attr_consistent,
-                        replace = True, and_source = False):
+    def update_all_atts(self, dict_, update_fun=copy_attr_consistent,
+                        replace=True, and_source=False):
         """
         Updates all attributes from node or dictionary `dict_`.
 
@@ -910,8 +882,8 @@ class Element(Node):
         for att in filter(filter_fun, dict_):
             update_fun(self, att, dict_[att], replace)
 
-    def update_all_atts_consistantly(self, dict_, replace = True,
-                                     and_source = False):
+    def update_all_atts_consistantly(self, dict_, replace=True,
+                                     and_source=False):
         """
         Updates all attributes from node or dictionary `dict_`.
 
@@ -931,8 +903,8 @@ class Element(Node):
         self.update_all_atts(dict_, Element.copy_attr_consistent, replace,
                              and_source)
 
-    def update_all_atts_concatenating(self, dict_, replace = True,
-                                      and_source = False):
+    def update_all_atts_concatenating(self, dict_, replace=True,
+                                      and_source=False):
         """
         Updates all attributes from node or dictionary `dict_`.
 
@@ -955,8 +927,8 @@ class Element(Node):
         self.update_all_atts(dict_, Element.copy_attr_concatenate, replace,
                              and_source)
 
-    def update_all_atts_coercion(self, dict_, replace = True,
-                                 and_source = False):
+    def update_all_atts_coercion(self, dict_, replace=True,
+                                 and_source=False):
         """
         Updates all attributes from node or dictionary `dict_`.
 
@@ -980,7 +952,7 @@ class Element(Node):
         self.update_all_atts(dict_, Element.copy_attr_coerce, replace,
                              and_source)
 
-    def update_all_atts_convert(self, dict_, and_source = False):
+    def update_all_atts_convert(self, dict_, and_source=False):
         """
         Updates all attributes from node or dictionary `dict_`.
 
@@ -999,7 +971,7 @@ class Element(Node):
               on the value of update_fun.
         """
         self.update_all_atts(dict_, Element.copy_attr_convert,
-                             and_source = and_source)
+                             and_source=and_source)
 
     def clear(self):
         self.children = []
@@ -1077,9 +1049,9 @@ class Element(Node):
         return None
 
     def pformat(self, indent='    ', level=0):
-        return ''.join(['%s%s\n' % (indent * level, self.starttag())] +
-                       [child.pformat(indent, level+1)
-                        for child in self.children])
+        tagline = '%s%s\n' % (indent*level, self.starttag())
+        childreps = (c.pformat(indent, level+1) for c in self.children)
+        return ''.join((tagline, *childreps))
 
     def copy(self):
         obj = self.__class__(rawsource=self.rawsource, **self.attributes)
@@ -1095,8 +1067,9 @@ class Element(Node):
 
     def set_class(self, name):
         """Add a new class to the "classes" attribute."""
-        warnings.warn('docutils.nodes.Element.set_class deprecated; '
-                      "append to Element['classes'] list attribute directly",
+        warnings.warn('docutils.nodes.Element.set_class() is deprecated; '
+                      ' and will be removed in Docutils 0.21 or later.'
+                      "Append to Element['classes'] list attribute directly",
                       DeprecationWarning, stacklevel=2)
         assert ' ' not in name
         self['classes'].append(name.lower())
@@ -1157,7 +1130,7 @@ class TextElement(Element):
         if text != '':
             textnode = Text(text)
             Element.__init__(self, rawsource, textnode, *children,
-                              **attributes)
+                             **attributes)
         else:
             Element.__init__(self, rawsource, *children, **attributes)
 
@@ -1175,12 +1148,12 @@ class FixedTextElement(TextElement):
 #  Mixins
 # ========
 
-class Resolvable(object):
+class Resolvable:
 
     resolved = 0
 
 
-class BackLinkable(object):
+class BackLinkable:
 
     def add_backref(self, refid):
         self['backrefs'].append(refid)
@@ -1190,19 +1163,19 @@ class BackLinkable(object):
 #  Element Categories
 # ====================
 
-class Root(object):
+class Root:
     pass
 
 
-class Titular(object):
+class Titular:
     pass
 
 
-class PreBibliographic(object):
+class PreBibliographic:
     """Category of Node which may occur before Bibliographic Nodes."""
 
 
-class Bibliographic(object):
+class Bibliographic:
     pass
 
 
@@ -1210,11 +1183,11 @@ class Decorative(PreBibliographic):
     pass
 
 
-class Structural(object):
+class Structural:
     pass
 
 
-class Body(object):
+class Body:
     pass
 
 
@@ -1237,11 +1210,11 @@ class Invisible(PreBibliographic):
     """Internal elements that don't appear in output."""
 
 
-class Part(object):
+class Part:
     pass
 
 
-class Inline(object):
+class Inline:
     pass
 
 
@@ -1258,7 +1231,7 @@ class Targetable(Resolvable):
     Required for MoinMoin/reST compatibility."""
 
 
-class Labeled(object):
+class Labeled:
     """Contains a `label` as its first element."""
 
 
@@ -1406,7 +1379,7 @@ class document(Root, Structural, Element):
                 self.ids.setdefault(id, node)
                 if self.ids[id] is not node:
                     msg = self.reporter.severe('Duplicate ID: "%s".' % id)
-                    if msgnode != None:
+                    if msgnode is not None:
                         msgnode += msg
             return id
         # generate and set id
@@ -1415,10 +1388,13 @@ class document(Root, Structural, Element):
         base_id = ''
         id = ''
         for name in node['names']:
-            base_id = make_id(name)
+            if id_prefix:
+                # allow names starting with numbers if `id_prefix`
+                base_id = make_id('x'+name)[1:]
+            else:
+                base_id = make_id(name)
+            # TODO: normalize id-prefix? (would make code simpler)
             id = id_prefix + base_id
-            # TODO: allow names starting with numbers if `id_prefix`
-            # is non-empty:  id = make_id(id_prefix + name)
             if base_id and id not in self.ids:
                 break
         else:
@@ -1428,9 +1404,10 @@ class document(Root, Structural, Element):
                 prefix = id + '-'
             else:
                 prefix = id_prefix + auto_id_prefix
-                if  prefix.endswith('%'):
-                    prefix = '%s%s-' % (prefix[:-1], suggested_prefix
-                                                or make_id(node.tagname))
+                if prefix.endswith('%'):
+                    prefix = '%s%s-' % (prefix[:-1],
+                                        suggested_prefix
+                                        or make_id(node.tagname))
             while True:
                 self.id_counter[prefix] += 1
                 id = '%s%d' % (prefix, self.id_counter[prefix])
@@ -1468,25 +1445,26 @@ class document(Root, Structural, Element):
         booleans representing hyperlink type (True==explicit,
         False==implicit).  This method updates the mappings.
 
-        The following state transition table shows how `self.nameids` ("ids")
-        and `self.nametypes` ("types") change with new input (a call to this
-        method), and what actions are performed ("implicit"-type system
-        messages are INFO/1, and "explicit"-type system messages are ERROR/3):
+        The following state transition table shows how `self.nameids` items
+        ("id") and `self.nametypes` items ("type") change with new input
+        (a call to this method), and what actions are performed
+        ("implicit"-type system messages are INFO/1, and
+        "explicit"-type system messages are ERROR/3):
 
         ====  =====  ========  ========  =======  ====  =====  =====
          Old State    Input          Action        New State   Notes
         -----------  --------  -----------------  -----------  -----
-        ids   types  new type  sys.msg.  dupname  ids   types
+        id    type   new type  sys.msg.  dupname  id    type
         ====  =====  ========  ========  =======  ====  =====  =====
         -     -      explicit  -         -        new   True
         -     -      implicit  -         -        new   False
-        None  False  explicit  -         -        new   True
+        -     False  explicit  -         -        new   True
         old   False  explicit  implicit  old      new   True
-        None  True   explicit  explicit  new      None  True
-        old   True   explicit  explicit  new,old  None  True   [#]_
-        None  False  implicit  implicit  new      None  False
-        old   False  implicit  implicit  new,old  None  False
-        None  True   implicit  implicit  new      None  True
+        -     True   explicit  explicit  new      -     True
+        old   True   explicit  explicit  new,old  -     True   [#]_
+        -     False  implicit  implicit  new      -     False
+        old   False  implicit  implicit  new,old  -     False
+        -     True   implicit  implicit  new      -     True
         old   True   implicit  implicit  new      old   True
         ====  =====  ========  ========  =======  ====  =====  =====
 
@@ -1494,9 +1472,10 @@ class document(Root, Structural, Element):
            both old and new targets are external and refer to identical URIs.
            The new target is invalidated regardless.
         """
-        for name in node['names']:
+        for name in tuple(node['names']):
             if name in self.nameids:
                 self.set_duplicate_name_id(node, id, name, msgnode, explicit)
+                # attention: modifies node['names']
             else:
                 self.nameids[name] = id
                 self.nametypes[name] = explicit
@@ -1512,9 +1491,9 @@ class document(Root, Structural, Element):
                     old_node = self.ids[old_id]
                     if 'refuri' in node:
                         refuri = node['refuri']
-                        if old_node['names'] \
-                               and 'refuri' in old_node \
-                               and old_node['refuri'] == refuri:
+                        if (old_node['names']
+                            and 'refuri' in old_node
+                            and old_node['refuri'] == refuri):
                             level = 1   # just inform if refuri's identical
                     if level > 1:
                         dupname(old_node, name)
@@ -1522,7 +1501,7 @@ class document(Root, Structural, Element):
                 msg = self.reporter.system_message(
                     level, 'Duplicate explicit target name: "%s".' % name,
                     backrefs=[id], base_node=node)
-                if msgnode != None:
+                if msgnode is not None:
                     msgnode += msg
                 dupname(node, name)
             else:
@@ -1540,7 +1519,7 @@ class document(Root, Structural, Element):
             msg = self.reporter.info(
                 'Duplicate implicit target name: "%s".' % name,
                 backrefs=[id], base_node=node)
-            if msgnode != None:
+            if msgnode is not None:
                 msgnode += msg
 
     def has_name(self, name):
@@ -1549,7 +1528,7 @@ class document(Root, Structural, Element):
     # "note" here is an imperative verb: "take note of".
     def note_implicit_target(self, target, msgnode=None):
         id = self.set_id(target, msgnode)
-        self.set_name_id_map(target, id, msgnode, explicit=None)
+        self.set_name_id_map(target, id, msgnode, explicit=False)
 
     def note_explicit_target(self, target, msgnode=None):
         id = self.set_id(target, msgnode)
@@ -1606,9 +1585,9 @@ class document(Root, Structural, Element):
         name = whitespace_normalize_name(def_name)
         if name in self.substitution_defs:
             msg = self.reporter.error(
-                  'Duplicate substitution definition name: "%s".' % name,
-                  base_node=subdef)
-            if msgnode != None:
+                      'Duplicate substitution definition name: "%s".' % name,
+                      base_node=subdef)
+            if msgnode is not None:
                 msgnode += msg
             oldnode = self.substitution_defs[name]
             dupname(oldnode, name)
@@ -1638,7 +1617,7 @@ class document(Root, Structural, Element):
 
     def copy(self):
         obj = self.__class__(self.settings, self.reporter,
-                              **self.attributes)
+                             **self.attributes)
         obj.source = self.source
         obj.line = self.line
         return obj
@@ -1646,7 +1625,7 @@ class document(Root, Structural, Element):
     def get_decoration(self):
         if not self.decoration:
             self.decoration = decoration()
-            index = self.first_child_not_matching_class(Titular)
+            index = self.first_child_not_matching_class((Titular, meta))
             if index is None:
                 self.append(self.decoration)
             else:
@@ -1663,6 +1642,14 @@ class subtitle(Titular, PreBibliographic, TextElement): pass
 class rubric(Titular, TextElement): pass
 
 
+# ==================
+#  Meta-Data Element
+# ==================
+
+class meta(PreBibliographic, Element):
+    """Container for "invisible" bibliographic data, or meta-data."""
+
+
 # ========================
 #  Bibliographic Elements
 # ========================
@@ -1846,14 +1833,14 @@ class system_message(Special, BackLinkable, PreBibliographic, Element):
             children = (p,) + children
         try:
             Element.__init__(self, rawsource, *children, **attributes)
-        except:
+        except:  # noqa  catchall
             print('system_message: children=%r' % (children,))
             raise
 
     def astext(self):
         line = self.get('line', '')
-        return u'%s:%s: (%s/%s) %s' % (self['source'], line, self['type'],
-                                       self['level'], Element.astext(self))
+        return '%s:%s: (%s/%s) %s' % (self['source'], line, self['type'],
+                                      self['level'], Element.astext(self))
 
 
 class pending(Special, Invisible, Element):
@@ -1896,19 +1883,19 @@ class pending(Special, Invisible, Element):
         """Detail data (dictionary) required by the pending operation."""
 
     def pformat(self, indent='    ', level=0):
-        internals = [
-              '.. internal attributes:',
-              '     .transform: %s.%s' % (self.transform.__module__,
-                                          self.transform.__name__),
-              '     .details:']
+        internals = ['.. internal attributes:',
+                     '     .transform: %s.%s' % (self.transform.__module__,
+                                                 self.transform.__name__),
+                     '     .details:']
         details = sorted(self.details.items())
         for key, value in details:
             if isinstance(value, Node):
                 internals.append('%7s%s:' % ('', key))
                 internals.extend(['%9s%s' % ('', line)
                                   for line in value.pformat().splitlines()])
-            elif value and isinstance(value, list) \
-                  and isinstance(value[0], Node):
+            elif (value
+                  and isinstance(value, list)
+                  and isinstance(value[0], Node)):
                 internals.append('%7s%s:' % ('', key))
                 for v in value:
                     internals.extend(['%9s%s' % ('', line)
@@ -1916,12 +1903,12 @@ class pending(Special, Invisible, Element):
             else:
                 internals.append('%7s%s: %r' % ('', key, value))
         return (Element.pformat(self, indent, level)
-                + ''.join([('    %s%s\n' % (indent * level, line))
-                           for line in internals]))
+                + ''.join(('    %s%s\n' % (indent * level, line))
+                          for line in internals))
 
     def copy(self):
         obj = self.__class__(self.transform, self.details, self.rawsource,
-                              **self.attributes)
+                             **self.attributes)
         obj._document = self._document
         obj.source = self.source
         obj.line = self.line
@@ -1934,8 +1921,6 @@ class raw(Special, Inline, PreBibliographic, FixedTextElement):
     Raw data that is to be passed untouched to the Writer.
     """
 
-    pass
-
 
 # =================
 #  Inline Elements
@@ -1987,7 +1972,7 @@ node_class_names = """
     header hint
     image important inline
     label legend line line_block list_item literal literal_block
-    math math_block
+    math math_block meta
     note
     option option_argument option_group option_list option_list_item
         option_string organization
@@ -2002,7 +1987,7 @@ node_class_names = """
 """A list of names of all concrete Node subclasses."""
 
 
-class NodeVisitor(object):
+class NodeVisitor:
 
     """
     "Visitor" pattern [GoF95]_ abstract superclass implementation for
@@ -2018,9 +2003,9 @@ class NodeVisitor(object):
     "``depart_`` + node class name", resp.
 
     This is a base class for visitors whose ``visit_...`` & ``depart_...``
-    methods should be implemented for *all* node types encountered (such as
-    for `docutils.writers.Writer` subclasses).  Unimplemented methods will
-    raise exceptions.
+    methods must be implemented for *all* compulsory node types encountered
+    (such as for `docutils.writers.Writer` subclasses).
+    Unimplemented methods will raise exceptions (except for optional nodes).
 
     For sparse traversals, where only certain node types are of interest, use
     subclass `SparseNodeVisitor` instead.  When (mostly or entirely) uniform
@@ -2031,7 +2016,7 @@ class NodeVisitor(object):
        1995.
     """
 
-    optional = ()
+    optional = ('meta',)
     """
     Tuple containing node class names (as strings).
 
@@ -2076,8 +2061,8 @@ class NodeVisitor(object):
 
         Raise an exception unless overridden.
         """
-        if  (self.document.settings.strict_visitor
-             or node.__class__.__name__ not in self.optional):
+        if (self.document.settings.strict_visitor
+            or node.__class__.__name__ not in self.optional):
             raise NotImplementedError(
                 '%s visiting unknown node type: %s'
                 % (self.__class__, node.__class__.__name__))
@@ -2088,8 +2073,8 @@ class NodeVisitor(object):
 
         Raise exception unless overridden.
         """
-        if  (self.document.settings.strict_visitor
-             or node.__class__.__name__ not in self.optional):
+        if (self.document.settings.strict_visitor
+            or node.__class__.__name__ not in self.optional):
             raise NotImplementedError(
                 '%s departing unknown node type: %s'
                 % (self.__class__, node.__class__.__name__))
@@ -2131,15 +2116,19 @@ class GenericNodeVisitor(NodeVisitor):
         """Override for generic, uniform traversals."""
         raise NotImplementedError
 
+
 def _call_default_visit(self, node):
     self.default_visit(node)
 
+
 def _call_default_departure(self, node):
     self.default_departure(node)
 
+
 def _nop(self, node):
     pass
 
+
 def _add_node_class_names(names):
     """Save typing with dynamic assignments:"""
     for _name in names:
@@ -2148,6 +2137,7 @@ def _add_node_class_names(names):
         setattr(SparseNodeVisitor, 'visit_' + _name, _nop)
         setattr(SparseNodeVisitor, 'depart_' + _name, _nop)
 
+
 _add_node_class_names(node_class_names)
 
 
@@ -2187,8 +2177,6 @@ class TreePruningException(Exception):
     the tree traversed.
     """
 
-    pass
-
 
 class SkipChildren(TreePruningException):
 
@@ -2197,8 +2185,6 @@ class SkipChildren(TreePruningException):
     siblings and ``depart_...`` method are not affected.
     """
 
-    pass
-
 
 class SkipSiblings(TreePruningException):
 
@@ -2207,8 +2193,6 @@ class SkipSiblings(TreePruningException):
     current node's children and its ``depart_...`` method are not affected.
     """
 
-    pass
-
 
 class SkipNode(TreePruningException):
 
@@ -2217,8 +2201,6 @@ class SkipNode(TreePruningException):
     node's ``depart_...`` method.
     """
 
-    pass
-
 
 class SkipDeparture(TreePruningException):
 
@@ -2227,8 +2209,6 @@ class SkipDeparture(TreePruningException):
     children and siblings are not affected.
     """
 
-    pass
-
 
 class NodeFound(TreePruningException):
 
@@ -2238,21 +2218,17 @@ class NodeFound(TreePruningException):
     code.
     """
 
-    pass
-
 
 class StopTraversal(TreePruningException):
 
     """
-    Stop the traversal all together.  The current node's ``depart_...`` method
+    Stop the traversal altogether.  The current node's ``depart_...`` method
     is not affected.  The parent nodes ``depart_...`` methods are also called
     as usual.  No other nodes are visited.  This is an alternative to
     NodeFound that does not cause exception handling to trickle up to the
     caller.
     """
 
-    pass
-
 
 def make_id(string):
     """
@@ -2286,99 +2262,90 @@ def make_id(string):
     "unicode", "latin1", or "escape" characters), this results in the
     ``[a-z](-?[a-z0-9]+)*`` pattern.
 
-    .. _HTML 4.01 spec: http://www.w3.org/TR/html401
-    .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
+    .. _HTML 4.01 spec: https://www.w3.org/TR/html401
+    .. _CSS1 spec: https://www.w3.org/TR/REC-CSS1
     """
     id = string.lower()
-    if not isinstance(id, unicode):
-        id = id.decode()
     id = id.translate(_non_id_translate_digraphs)
     id = id.translate(_non_id_translate)
     # get rid of non-ascii characters.
     # 'ascii' lowercase to prevent problems with turkish locale.
-    id = unicodedata.normalize('NFKD', id).\
-         encode('ascii', 'ignore').decode('ascii')
+    id = unicodedata.normalize(
+            'NFKD', id).encode('ascii', 'ignore').decode('ascii')
     # shrink runs of whitespace and replace by hyphen
     id = _non_id_chars.sub('-', ' '.join(id.split()))
     id = _non_id_at_ends.sub('', id)
     return str(id)
 
+
 _non_id_chars = re.compile('[^a-z0-9]+')
 _non_id_at_ends = re.compile('^[-0-9]+|-+$')
 _non_id_translate = {
-    0x00f8: u'o',       # o with stroke
-    0x0111: u'd',       # d with stroke
-    0x0127: u'h',       # h with stroke
-    0x0131: u'i',       # dotless i
-    0x0142: u'l',       # l with stroke
-    0x0167: u't',       # t with stroke
-    0x0180: u'b',       # b with stroke
-    0x0183: u'b',       # b with topbar
-    0x0188: u'c',       # c with hook
-    0x018c: u'd',       # d with topbar
-    0x0192: u'f',       # f with hook
-    0x0199: u'k',       # k with hook
-    0x019a: u'l',       # l with bar
-    0x019e: u'n',       # n with long right leg
-    0x01a5: u'p',       # p with hook
-    0x01ab: u't',       # t with palatal hook
-    0x01ad: u't',       # t with hook
-    0x01b4: u'y',       # y with hook
-    0x01b6: u'z',       # z with stroke
-    0x01e5: u'g',       # g with stroke
-    0x0225: u'z',       # z with hook
-    0x0234: u'l',       # l with curl
-    0x0235: u'n',       # n with curl
-    0x0236: u't',       # t with curl
-    0x0237: u'j',       # dotless j
-    0x023c: u'c',       # c with stroke
-    0x023f: u's',       # s with swash tail
-    0x0240: u'z',       # z with swash tail
-    0x0247: u'e',       # e with stroke
-    0x0249: u'j',       # j with stroke
-    0x024b: u'q',       # q with hook tail
-    0x024d: u'r',       # r with stroke
-    0x024f: u'y',       # y with stroke
+    0x00f8: 'o',       # o with stroke
+    0x0111: 'd',       # d with stroke
+    0x0127: 'h',       # h with stroke
+    0x0131: 'i',       # dotless i
+    0x0142: 'l',       # l with stroke
+    0x0167: 't',       # t with stroke
+    0x0180: 'b',       # b with stroke
+    0x0183: 'b',       # b with topbar
+    0x0188: 'c',       # c with hook
+    0x018c: 'd',       # d with topbar
+    0x0192: 'f',       # f with hook
+    0x0199: 'k',       # k with hook
+    0x019a: 'l',       # l with bar
+    0x019e: 'n',       # n with long right leg
+    0x01a5: 'p',       # p with hook
+    0x01ab: 't',       # t with palatal hook
+    0x01ad: 't',       # t with hook
+    0x01b4: 'y',       # y with hook
+    0x01b6: 'z',       # z with stroke
+    0x01e5: 'g',       # g with stroke
+    0x0225: 'z',       # z with hook
+    0x0234: 'l',       # l with curl
+    0x0235: 'n',       # n with curl
+    0x0236: 't',       # t with curl
+    0x0237: 'j',       # dotless j
+    0x023c: 'c',       # c with stroke
+    0x023f: 's',       # s with swash tail
+    0x0240: 'z',       # z with swash tail
+    0x0247: 'e',       # e with stroke
+    0x0249: 'j',       # j with stroke
+    0x024b: 'q',       # q with hook tail
+    0x024d: 'r',       # r with stroke
+    0x024f: 'y',       # y with stroke
 }
 _non_id_translate_digraphs = {
-    0x00df: u'sz',      # ligature sz
-    0x00e6: u'ae',      # ae
-    0x0153: u'oe',      # ligature oe
-    0x0238: u'db',      # db digraph
-    0x0239: u'qp',      # qp digraph
+    0x00df: 'sz',      # ligature sz
+    0x00e6: 'ae',      # ae
+    0x0153: 'oe',      # ligature oe
+    0x0238: 'db',      # db digraph
+    0x0239: 'qp',      # qp digraph
 }
 
+
 def dupname(node, name):
-    # node['dupnames'].append(name)
-    # node['names'].remove(name)
-    # # Assume that this method is referenced, even though it isn't; we
-    # # don't want to throw unnecessary system_messages.
-    # node.referenced = 1
     node['dupnames'].append(name)
     if node['names']:
         node['names'].remove(name)
     node.referenced = 1
 
+
 def fully_normalize_name(name):
     """Return a case- and whitespace-normalized name."""
     return ' '.join(name.lower().split())
 
+
 def whitespace_normalize_name(name):
     """Return a whitespace-normalized name."""
     return ' '.join(name.split())
 
+
 def serial_escape(value):
     """Escape string values that are elements of a list, for serialization."""
     return value.replace('\\', r'\\').replace(' ', r'\ ')
 
+
 def pseudo_quoteattr(value):
     """Quote attributes for pseudo-xml"""
     return '"%s"' % value
-
-# 
-#
-# Local Variables:
-# indent-tabs-mode: nil
-# sentence-end-double-space: t
-# fill-column: 78
-# End:
diff --git a/resource/sphinx_ext/nodes_old.txt b/resource/sphinx_ext/nodes_old.txt
new file mode 100644
index 0000000000000000000000000000000000000000..faafc34ef0affa1e1d32368a8d51a7a68ac824a0
--- /dev/null
+++ b/resource/sphinx_ext/nodes_old.txt
@@ -0,0 +1,2384 @@
+# $Id: nodes.py 8592 2020-12-15 23:06:26Z milde $
+# Author: David Goodger <goodger@python.org>
+# Maintainer: docutils-develop@lists.sourceforge.net
+# Copyright: This module has been placed in the public domain.
+
+"""
+Docutils document tree element class library.
+
+Classes in CamelCase are abstract base classes or auxiliary classes. The one
+exception is `Text`, for a text (PCDATA) node; uppercase is used to
+differentiate from element classes.  Classes in lower_case_with_underscores
+are element classes, matching the XML element generic identifiers in the DTD_.
+
+The position of each node (the level at which it can occur) is significant and
+is represented by abstract base classes (`Root`, `Structural`, `Body`,
+`Inline`, etc.).  Certain transformations will be easier because we can use
+``isinstance(node, base_class)`` to determine the position of the node in the
+hierarchy.
+
+.. _DTD: http://docutils.sourceforge.net/docs/ref/docutils.dtd
+"""
+from __future__ import print_function
+from collections import Counter
+
+__docformat__ = 'reStructuredText'
+
+import sys
+import os
+import re
+import warnings
+import unicodedata
+
+if sys.version_info >= (3, 0):
+    unicode = str  # noqa
+    basestring = str  # noqa
+
+class _traversal_list(list):
+    # auxiliary class to report a FutureWarning
+    done = False
+    def _warning_decorator(fun):
+        msg = ("\n   The iterable returned by Node.traverse()"
+               "\n   will become an iterator instead of a list in "
+               "Docutils > 0.16.")
+        def wrapper(self, *args, **kwargs):
+            if not self.done:
+                warnings.warn(msg, FutureWarning, stacklevel=2)
+            self.done = True
+            return fun(self, *args, **kwargs)
+        return wrapper
+
+    __add__ = _warning_decorator(list.__add__)
+    __contains__ = _warning_decorator(list.__contains__)
+    __getitem__ = _warning_decorator(list.__getitem__)
+    __reversed__ = _warning_decorator(list.__reversed__)
+    __setitem__ = _warning_decorator(list.__setitem__)
+    append = _warning_decorator(list.append)
+    count = _warning_decorator(list.count)
+    extend = _warning_decorator(list.extend)
+    index = _warning_decorator(list.index)
+    insert = _warning_decorator(list.insert)
+    pop = _warning_decorator(list.pop)
+    reverse = _warning_decorator(list.reverse)
+
+
+# ==============================
+#  Functional Node Base Classes
+# ==============================
+
+class Node(object):
+
+    """Abstract base class of nodes in a document tree."""
+
+    parent = None
+    """Back-reference to the Node immediately containing this Node."""
+
+    source = None
+    """Path or description of the input source which generated this Node."""
+
+    line = None
+    """The line number (1-based) of the beginning of this Node in `source`."""
+
+    _document = None
+
+    @property
+    def document(self):
+        """
+        Return the `document` node at the root of the tree containing this Node.
+        """
+        try:
+            return self._document or self.parent.document
+        except AttributeError:
+            return None
+
+    @document.setter
+    def document(self, value):
+        self._document = value
+
+    def __bool__(self):
+        """
+        Node instances are always true, even if they're empty.  A node is more
+        than a simple container.  Its boolean "truth" does not depend on
+        having one or more subnodes in the doctree.
+
+        Use `len()` to check node length.  Use `None` to represent a boolean
+        false value.
+        """
+        return True
+
+    if sys.version_info < (3, 0):
+        __nonzero__ = __bool__
+
+    if sys.version_info < (3, 0):
+        # on 2.x, str(node) will be a byte string with Unicode
+        # characters > 255 escaped; on 3.x this is no longer necessary
+        def __str__(self):
+            return unicode(self).encode('raw_unicode_escape')
+
+    def asdom(self, dom=None):
+        """Return a DOM **fragment** representation of this Node."""
+        if dom is None:
+            import xml.dom.minidom as dom
+        domroot = dom.Document()
+        return self._dom_node(domroot)
+
+    def pformat(self, indent='    ', level=0):
+        """
+        Return an indented pseudo-XML representation, for test purposes.
+
+        Override in subclasses.
+        """
+        raise NotImplementedError
+
+    def copy(self):
+        """Return a copy of self."""
+        raise NotImplementedError
+
+    def deepcopy(self):
+        """Return a deep copy of self (also copying children)."""
+        raise NotImplementedError
+
+    def astext(self):
+        """Return a string representation of this Node."""
+        raise NotImplementedError
+
+    def setup_child(self, child):
+        child.parent = self
+        if self.document:
+            child.document = self.document
+            if child.source is None:
+                child.source = self.document.current_source
+            if child.line is None:
+                child.line = self.document.current_line
+
+    def walk(self, visitor):
+        """
+        Traverse a tree of `Node` objects, calling the
+        `dispatch_visit()` method of `visitor` when entering each
+        node.  (The `walkabout()` method is similar, except it also
+        calls the `dispatch_departure()` method before exiting each
+        node.)
+
+        This tree traversal supports limited in-place tree
+        modifications.  Replacing one node with one or more nodes is
+        OK, as is removing an element.  However, if the node removed
+        or replaced occurs after the current node, the old node will
+        still be traversed, and any new nodes will not.
+
+        Within ``visit`` methods (and ``depart`` methods for
+        `walkabout()`), `TreePruningException` subclasses may be raised
+        (`SkipChildren`, `SkipSiblings`, `SkipNode`, `SkipDeparture`).
+
+        Parameter `visitor`: A `NodeVisitor` object, containing a
+        ``visit`` implementation for each `Node` subclass encountered.
+
+        Return true if we should stop the traversal.
+        """
+        stop = False
+        visitor.document.reporter.debug(
+            'docutils.nodes.Node.walk calling dispatch_visit for %s'
+            % self.__class__.__name__)
+        try:
+            try:
+                visitor.dispatch_visit(self)
+            except (SkipChildren, SkipNode):
+                return stop
+            except SkipDeparture:           # not applicable; ignore
+                pass
+            children = self.children
+            try:
+                for child in children[:]:
+                    if child.walk(visitor):
+                        stop = True
+                        break
+            except SkipSiblings:
+                pass
+        except StopTraversal:
+            stop = True
+        return stop
+
+    def walkabout(self, visitor):
+        """
+        Perform a tree traversal similarly to `Node.walk()` (which
+        see), except also call the `dispatch_departure()` method
+        before exiting each node.
+
+        Parameter `visitor`: A `NodeVisitor` object, containing a
+        ``visit`` and ``depart`` implementation for each `Node`
+        subclass encountered.
+
+        Return true if we should stop the traversal.
+        """
+        call_depart = True
+        stop = False
+        visitor.document.reporter.debug(
+            'docutils.nodes.Node.walkabout calling dispatch_visit for %s'
+            % self.__class__.__name__)
+        try:
+            try:
+                visitor.dispatch_visit(self)
+            except SkipNode:
+                return stop
+            except SkipDeparture:
+                call_depart = False
+            children = self.children
+            try:
+                for child in children[:]:
+                    if child.walkabout(visitor):
+                        stop = True
+                        break
+            except SkipSiblings:
+                pass
+        except SkipChildren:
+            pass
+        except StopTraversal:
+            stop = True
+        if call_depart:
+            visitor.document.reporter.debug(
+                'docutils.nodes.Node.walkabout calling dispatch_departure '
+                'for %s' % self.__class__.__name__)
+            visitor.dispatch_departure(self)
+        return stop
+
+    def _fast_traverse(self, cls):
+        """Return iterator that only supports instance checks."""
+        if isinstance(self, cls):
+            yield self
+        for child in self.children:
+            for subnode in child._fast_traverse(cls):
+                yield subnode
+
+    def _all_traverse(self):
+        """Return iterator that doesn't check for a condition."""
+        yield self
+        for child in self.children:
+            for subnode in child._all_traverse():
+                yield subnode
+
+    def traverse(self, condition=None, include_self=True, descend=True,
+                 siblings=False, ascend=False):
+        """
+        Return an iterable containing
+
+        * self (if include_self is true)
+        * all descendants in tree traversal order (if descend is true)
+        * all siblings (if siblings is true) and their descendants (if
+          also descend is true)
+        * the siblings of the parent (if ascend is true) and their
+          descendants (if also descend is true), and so on
+
+        If `condition` is not None, the iterable contains only nodes
+        for which ``condition(node)`` is true.  If `condition` is a
+        node class ``cls``, it is equivalent to a function consisting
+        of ``return isinstance(node, cls)``.
+
+        If ascend is true, assume siblings to be true as well.
+
+        For example, given the following tree::
+
+            <paragraph>
+                <emphasis>      <--- emphasis.traverse() and
+                    <strong>    <--- strong.traverse() are called.
+                        Foo
+                    Bar
+                <reference name="Baz" refid="baz">
+                    Baz
+
+        Then list(emphasis.traverse()) equals ::
+
+            [<emphasis>, <strong>, <#text: Foo>, <#text: Bar>]
+
+        and list(strong.traverse(ascend=True)) equals ::
+
+            [<strong>, <#text: Foo>, <#text: Bar>, <reference>, <#text: Baz>]
+        """
+        # Although the documented API only promises an "iterable" as return
+        # value, the implementation returned a list up to v. 0.15. Some 3rd
+        # party code still relies on this (e.g. Sphinx as of 2019-09-07).
+        # Therefore, let's return a list until this is sorted out:
+        return _traversal_list(self._traverse(condition, include_self,
+                                   descend, siblings, ascend))
+
+    def _traverse(self, condition=None, include_self=True, descend=True,
+                  siblings=False, ascend=False):
+        """Return iterator over nodes following `self`. See `traverse()`."""
+        if ascend:
+            siblings=True
+        # Check for special argument combinations that allow using an
+        # optimized version of traverse()
+        if include_self and descend and not siblings:
+            if condition is None:
+                for subnode in self._all_traverse():
+                    yield subnode
+                return
+            elif isinstance(condition, type):
+                for subnode in self._fast_traverse(condition):
+                    yield subnode
+                return
+        # Check if `condition` is a class (check for TypeType for Python
+        # implementations that use only new-style classes, like PyPy).
+        if isinstance(condition, type):
+            node_class = condition
+            def condition(node, node_class=node_class):
+                return isinstance(node, node_class)
+
+
+        if include_self and (condition is None or condition(self)):
+            yield self
+        if descend and len(self.children):
+            for child in self:
+                for subnode in child._traverse(condition=condition,
+                                    include_self=True, descend=True,
+                                    siblings=False, ascend=False):
+                    yield subnode
+        if siblings or ascend:
+            node = self
+            while node.parent:
+                index = node.parent.index(node)
+                for sibling in node.parent[index+1:]:
+                    for subnode in sibling._traverse(condition=condition,
+                                        include_self=True, descend=descend,
+                                        siblings=False, ascend=False):
+                        yield subnode
+                if not ascend:
+                    break
+                else:
+                    node = node.parent
+
+    def next_node(self, condition=None, include_self=False, descend=True,
+                  siblings=False, ascend=False):
+        """
+        Return the first node in the iterable returned by traverse(),
+        or None if the iterable is empty.
+
+        Parameter list is the same as of traverse.  Note that
+        include_self defaults to False, though.
+        """
+        node_iterator = self._traverse(condition, include_self,
+                                      descend, siblings, ascend)
+        try:
+            return next(node_iterator)
+        except StopIteration:
+            return None
+
+if sys.version_info < (3, 0):
+    class reprunicode(unicode):
+        """
+        A unicode sub-class that removes the initial u from unicode's repr.
+        """
+
+        def __repr__(self):
+            return unicode.__repr__(self)[1:]
+else:
+    reprunicode = unicode
+
+
+def ensure_str(s):
+    """
+    Fail-safe conversion of `unicode` to `str`.
+    """
+    if sys.version_info < (3, 0) and isinstance(s, unicode):
+        return s.encode('ascii', 'backslashreplace')
+    return s
+
+# definition moved here from `utils` to avoid circular import dependency
+def unescape(text, restore_backslashes=False, respect_whitespace=False):
+    """
+    Return a string with nulls removed or restored to backslashes.
+    Backslash-escaped spaces are also removed.
+    """
+    # `respect_whitespace` is ignored (since introduction 2016-12-16)
+    if restore_backslashes:
+        return text.replace('\x00', '\\')
+    else:
+        for sep in ['\x00 ', '\x00\n', '\x00']:
+            text = ''.join(text.split(sep))
+        return text
+
+
+class Text(Node, reprunicode):
+
+    """
+    Instances are terminal nodes (leaves) containing text only; no child
+    nodes or attributes.  Initialize by passing a string to the constructor.
+    Access the text itself with the `astext` method.
+    """
+
+    tagname = '#text'
+
+    children = ()
+    """Text nodes have no children, and cannot have children."""
+
+    if sys.version_info > (3, 0):
+        def __new__(cls, data, rawsource=None):
+            """Prevent the rawsource argument from propagating to str."""
+            if isinstance(data, bytes):
+                raise TypeError('expecting str data, not bytes')
+            return reprunicode.__new__(cls, data)
+    else:
+        def __new__(cls, data, rawsource=None):
+            """Prevent the rawsource argument from propagating to str."""
+            return reprunicode.__new__(cls, data)
+
+    def __init__(self, data, rawsource=''):
+        self.rawsource = rawsource
+        """The raw text from which this element was constructed."""
+
+    def shortrepr(self, maxlen=18):
+        data = self
+        if len(data) > maxlen:
+            data = data[:maxlen-4] + ' ...'
+        return '<%s: %r>' % (self.tagname, reprunicode(data))
+
+    def __repr__(self):
+        return self.shortrepr(maxlen=68)
+
+    def _dom_node(self, domroot):
+        return domroot.createTextNode(unicode(self))
+
+    def astext(self):
+        return reprunicode(unescape(self))
+
+    # Note about __unicode__: The implementation of __unicode__ here,
+    # and the one raising NotImplemented in the superclass Node had
+    # to be removed when changing Text to a subclass of unicode instead
+    # of UserString, since there is no way to delegate the __unicode__
+    # call to the superclass unicode:
+    # unicode itself does not have __unicode__ method to delegate to
+    # and calling unicode(self) or unicode.__new__ directly creates
+    # an infinite loop
+
+    def copy(self):
+        return self.__class__(reprunicode(self), rawsource=self.rawsource)
+
+    def deepcopy(self):
+        return self.copy()
+
+    def pformat(self, indent='    ', level=0):
+        try:
+            if self.document.settings.detailled:
+                lines = ['%s%s' % (indent * level, '<#text>')
+                        ] + [indent*(level+1) + repr(line)
+                             for line in self.splitlines(keepends=True)]
+                return '\n'.join(lines) + '\n'
+        except AttributeError:
+            pass
+        indent = indent * level
+        lines = [indent+line for line in self.astext().splitlines()]
+        if not lines:
+            return ''
+        return '\n'.join(lines) + '\n'
+
+    # rstrip and lstrip are used by substitution definitions where
+    # they are expected to return a Text instance, this was formerly
+    # taken care of by UserString.
+
+    def rstrip(self, chars=None):
+        return self.__class__(reprunicode.rstrip(self, chars), self.rawsource)
+
+    def lstrip(self, chars=None):
+        return self.__class__(reprunicode.lstrip(self, chars), self.rawsource)
+
+class Element(Node):
+
+    """
+    `Element` is the superclass to all specific elements.
+
+    Elements contain attributes and child nodes.  Elements emulate
+    dictionaries for attributes, indexing by attribute name (a string).  To
+    set the attribute 'att' to 'value', do::
+
+        element['att'] = 'value'
+
+    There are two special attributes: 'ids' and 'names'.  Both are
+    lists of unique identifiers, and names serve as human interfaces
+    to IDs.  Names are case- and whitespace-normalized (see the
+    fully_normalize_name() function), and IDs conform to the regular
+    expression ``[a-z](-?[a-z0-9]+)*`` (see the make_id() function).
+
+    Elements also emulate lists for child nodes (element nodes and/or text
+    nodes), indexing by integer.  To get the first child node, use::
+
+        element[0]
+
+    Elements may be constructed using the ``+=`` operator.  To add one new
+    child node to element, do::
+
+        element += node
+
+    This is equivalent to ``element.append(node)``.
+
+    To add a list of multiple child nodes at once, use the same ``+=``
+    operator::
+
+        element += [node1, node2]
+
+    This is equivalent to ``element.extend([node1, node2])``.
+    """
+
+    basic_attributes = ('ids', 'classes', 'names', 'dupnames')
+    """List attributes which are defined for every Element-derived class
+    instance and can be safely transferred to a different node."""
+
+    local_attributes = ('backrefs',)
+    """A list of class-specific attributes that should not be copied with the
+    standard attributes when replacing a node.
+
+    NOTE: Derived classes should override this value to prevent any of its
+    attributes being copied by adding to the value in its parent class."""
+
+    list_attributes = basic_attributes + local_attributes
+    """List attributes, automatically initialized to empty lists for
+    all nodes."""
+
+    known_attributes = list_attributes + ('source', 'rawsource')
+    """List attributes that are known to the Element base class."""
+
+    tagname = None
+    """The element generic identifier. If None, it is set as an instance
+    attribute to the name of the class."""
+
+    child_text_separator = '\n\n'
+    """Separator for child nodes, used by `astext()` method."""
+
+    def __init__(self, rawsource='', *children, **attributes):
+        self.rawsource = rawsource
+        """The raw text from which this element was constructed.
+
+        NOTE: some elements do not set this value (default '').
+        """
+
+        self.children = []
+        """List of child nodes (elements and/or `Text`)."""
+
+        self.extend(children)           # maintain parent info
+
+        self.attributes = {}
+        """Dictionary of attribute {name: value}."""
+
+        # Initialize list attributes.
+        for att in self.list_attributes:
+            self.attributes[att] = []
+
+        for att, value in attributes.items():
+            att = att.lower()
+            if att in self.list_attributes:
+                # mutable list; make a copy for this node
+                self.attributes[att] = value[:]
+            else:
+                self.attributes[att] = value
+
+        if self.tagname is None:
+            self.tagname = self.__class__.__name__
+
+    def _dom_node(self, domroot):
+        element = domroot.createElement(self.tagname)
+        for attribute, value in self.attlist():
+            if isinstance(value, list):
+                value = ' '.join([serial_escape('%s' % (v,)) for v in value])
+            element.setAttribute(attribute, '%s' % value)
+        for child in self.children:
+            element.appendChild(child._dom_node(domroot))
+        return element
+
+    def __repr__(self):
+        data = ''
+        for c in self.children:
+            data += c.shortrepr()
+            if len(data) > 60:
+                data = data[:56] + ' ...'
+                break
+        if self['names']:
+            return '<%s "%s": %s>' % (self.__class__.__name__,
+                '; '.join([ensure_str(n) for n in self['names']]), data)
+        else:
+            return '<%s: %s>' % (self.__class__.__name__, data)
+
+    def shortrepr(self):
+        if self['names']:
+            return '<%s "%s"...>' % (self.__class__.__name__,
+                '; '.join([ensure_str(n) for n in self['names']]))
+        else:
+            return '<%s...>' % self.tagname
+
+    def __unicode__(self):
+        if self.children:
+            return u'%s%s%s' % (self.starttag(),
+                                ''.join([unicode(c) for c in self.children]),
+                                self.endtag())
+        else:
+            return self.emptytag()
+
+    if sys.version_info >= (3, 0):
+        __str__ = __unicode__
+
+    def starttag(self, quoteattr=None):
+        # the optional arg is used by the docutils_xml writer
+        if quoteattr is None:
+            quoteattr = pseudo_quoteattr
+        parts = [self.tagname]
+        for name, value in self.attlist():
+            if value is None:           # boolean attribute
+                parts.append('%s="True"' % name)
+                continue
+            if isinstance(value, list):
+                values = [serial_escape('%s' % (v,)) for v in value]
+                value = ' '.join(values)
+            else:
+                value = unicode(value)
+            value = quoteattr(value)
+            parts.append(u'%s=%s' % (name, value))
+        return u'<%s>' % u' '.join(parts)
+
+    def endtag(self):
+        return '</%s>' % self.tagname
+
+    def emptytag(self):
+        return u'<%s/>' % u' '.join([self.tagname] +
+                                    ['%s="%s"' % (n, v)
+                                     for n, v in self.attlist()])
+
+    def __len__(self):
+        return len(self.children)
+
+    def __contains__(self, key):
+        # Test for both, children and attributes with operator ``in``.
+        if isinstance(key, basestring):
+            return key in self.attributes
+        return key in self.children
+
+    def __getitem__(self, key):
+        if isinstance(key, basestring):
+            return self.attributes[key]
+        elif isinstance(key, int):
+            return self.children[key]
+        elif isinstance(key, slice):
+            assert key.step in (None, 1), 'cannot handle slice with stride'
+            return self.children[key.start:key.stop]
+        else:
+            raise TypeError('element index must be an integer, a slice, or '
+                            'an attribute name string')
+
+    def __setitem__(self, key, item):
+        if isinstance(key, basestring):
+            self.attributes[str(key)] = item
+        elif isinstance(key, int):
+            self.setup_child(item)
+            self.children[key] = item
+        elif isinstance(key, slice):
+            assert key.step in (None, 1), 'cannot handle slice with stride'
+            for node in item:
+                self.setup_child(node)
+            self.children[key.start:key.stop] = item
+        else:
+            raise TypeError('element index must be an integer, a slice, or '
+                            'an attribute name string')
+
+    def __delitem__(self, key):
+        if isinstance(key, basestring):
+            del self.attributes[key]
+        elif isinstance(key, int):
+            del self.children[key]
+        elif isinstance(key, slice):
+            assert key.step in (None, 1), 'cannot handle slice with stride'
+            del self.children[key.start:key.stop]
+        else:
+            raise TypeError('element index must be an integer, a simple '
+                            'slice, or an attribute name string')
+
+    def __add__(self, other):
+        return self.children + other
+
+    def __radd__(self, other):
+        return other + self.children
+
+    def __iadd__(self, other):
+        """Append a node or a list of nodes to `self.children`."""
+        if isinstance(other, Node):
+            self.append(other)
+        elif other is not None:
+            self.extend(other)
+        return self
+
+    def astext(self):
+        return self.child_text_separator.join(
+              [child.astext() for child in self.children])
+
+    def non_default_attributes(self):
+        atts = {}
+        for key, value in self.attributes.items():
+            if self.is_not_default(key):
+                atts[key] = value
+        return atts
+
+    def attlist(self):
+        attlist = sorted(self.non_default_attributes().items())
+        return attlist
+
+    def get(self, key, failobj=None):
+        return self.attributes.get(key, failobj)
+
+    def hasattr(self, attr):
+        return attr in self.attributes
+
+    def delattr(self, attr):
+        if attr in self.attributes:
+            del self.attributes[attr]
+
+    def setdefault(self, key, failobj=None):
+        return self.attributes.setdefault(key, failobj)
+
+    has_key = hasattr
+
+    def get_language_code(self, fallback=''):
+        """Return node's language tag.
+
+        Look iteratively in self and parents for a class argument
+        starting with ``language-`` and return the remainder of it
+        (which should be a `BCP49` language tag) or the `fallback`.
+        """
+        for cls in self.get('classes', []):
+            if cls.startswith('language-'):
+                return cls[9:]
+        try:
+            return self.parent.get_language(fallback)
+        except AttributeError:
+            return fallback
+
+    def append(self, item):
+        self.setup_child(item)
+        self.children.append(item)
+
+    def extend(self, item):
+        for node in item:
+            self.append(node)
+
+    def insert(self, index, item):
+        if isinstance(item, Node):
+            self.setup_child(item)
+            self.children.insert(index, item)
+        elif item is not None:
+            self[index:index] = item
+
+    def pop(self, i=-1):
+        return self.children.pop(i)
+
+    def remove(self, item):
+        self.children.remove(item)
+
+    def index(self, item):
+        return self.children.index(item)
+
+    def is_not_default(self, key):
+        if self[key] == [] and key in self.list_attributes:
+            return 0
+        else:
+            return 1
+
+    def update_basic_atts(self, dict_):
+        """
+        Update basic attributes ('ids', 'names', 'classes',
+        'dupnames', but not 'source') from node or dictionary `dict_`.
+        """
+        if isinstance(dict_, Node):
+            dict_ = dict_.attributes
+        for att in self.basic_attributes:
+            self.append_attr_list(att, dict_.get(att, []))
+
+    def append_attr_list(self, attr, values):
+        """
+        For each element in values, if it does not exist in self[attr], append
+        it.
+
+        NOTE: Requires self[attr] and values to be sequence type and the
+        former should specifically be a list.
+        """
+        # List Concatenation
+        for value in values:
+            if not value in self[attr]:
+                self[attr].append(value)
+
+    def coerce_append_attr_list(self, attr, value):
+        """
+        First, convert both self[attr] and value to a non-string sequence
+        type; if either is not already a sequence, convert it to a list of one
+        element.  Then call append_attr_list.
+
+        NOTE: self[attr] and value both must not be None.
+        """
+        # List Concatenation
+        if not isinstance(self.get(attr), list):
+            self[attr] = [self[attr]]
+        if not isinstance(value, list):
+            value = [value]
+        self.append_attr_list(attr, value)
+
+    def replace_attr(self, attr, value, force = True):
+        """
+        If self[attr] does not exist or force is True or omitted, set
+        self[attr] to value, otherwise do nothing.
+        """
+        # One or the other
+        if force or self.get(attr) is None:
+            self[attr] = value
+
+    def copy_attr_convert(self, attr, value, replace = True):
+        """
+        If attr is an attribute of self, set self[attr] to
+        [self[attr], value], otherwise set self[attr] to value.
+
+        NOTE: replace is not used by this function and is kept only for
+              compatibility with the other copy functions.
+        """
+        if self.get(attr) is not value:
+            self.coerce_append_attr_list(attr, value)
+
+    def copy_attr_coerce(self, attr, value, replace):
+        """
+        If attr is an attribute of self and either self[attr] or value is a
+        list, convert all non-sequence values to a sequence of 1 element and
+        then concatenate the two sequence, setting the result to self[attr].
+        If both self[attr] and value are non-sequences and replace is True or
+        self[attr] is None, replace self[attr] with value. Otherwise, do
+        nothing.
+        """
+        if self.get(attr) is not value:
+            if isinstance(self.get(attr), list) or \
+               isinstance(value, list):
+                self.coerce_append_attr_list(attr, value)
+            else:
+                self.replace_attr(attr, value, replace)
+
+    def copy_attr_concatenate(self, attr, value, replace):
+        """
+        If attr is an attribute of self and both self[attr] and value are
+        lists, concatenate the two sequences, setting the result to
+        self[attr].  If either self[attr] or value are non-sequences and
+        replace is True or self[attr] is None, replace self[attr] with value.
+        Otherwise, do nothing.
+        """
+        if self.get(attr) is not value:
+            if isinstance(self.get(attr), list) and \
+               isinstance(value, list):
+                self.append_attr_list(attr, value)
+            else:
+                self.replace_attr(attr, value, replace)
+
+    def copy_attr_consistent(self, attr, value, replace):
+        """
+        If replace is True or self[attr] is None, replace self[attr] with
+        value.  Otherwise, do nothing.
+        """
+        if self.get(attr) is not value:
+            self.replace_attr(attr, value, replace)
+
+    def update_all_atts(self, dict_, update_fun = copy_attr_consistent,
+                        replace = True, and_source = False):
+        """
+        Updates all attributes from node or dictionary `dict_`.
+
+        Appends the basic attributes ('ids', 'names', 'classes',
+        'dupnames', but not 'source') and then, for all other attributes in
+        dict_, updates the same attribute in self.  When attributes with the
+        same identifier appear in both self and dict_, the two values are
+        merged based on the value of update_fun.  Generally, when replace is
+        True, the values in self are replaced or merged with the values in
+        dict_; otherwise, the values in self may be preserved or merged.  When
+        and_source is True, the 'source' attribute is included in the copy.
+
+        NOTE: When replace is False, and self contains a 'source' attribute,
+              'source' is not replaced even when dict_ has a 'source'
+              attribute, though it may still be merged into a list depending
+              on the value of update_fun.
+        NOTE: It is easier to call the update-specific methods then to pass
+              the update_fun method to this function.
+        """
+        if isinstance(dict_, Node):
+            dict_ = dict_.attributes
+
+        # Include the source attribute when copying?
+        if and_source:
+            filter_fun = self.is_not_list_attribute
+        else:
+            filter_fun = self.is_not_known_attribute
+
+        # Copy the basic attributes
+        self.update_basic_atts(dict_)
+
+        # Grab other attributes in dict_ not in self except the
+        # (All basic attributes should be copied already)
+        for att in filter(filter_fun, dict_):
+            update_fun(self, att, dict_[att], replace)
+
+    def update_all_atts_consistantly(self, dict_, replace = True,
+                                     and_source = False):
+        """
+        Updates all attributes from node or dictionary `dict_`.
+
+        Appends the basic attributes ('ids', 'names', 'classes',
+        'dupnames', but not 'source') and then, for all other attributes in
+        dict_, updates the same attribute in self.  When attributes with the
+        same identifier appear in both self and dict_ and replace is True, the
+        values in self are replaced with the values in dict_; otherwise, the
+        values in self are preserved.  When and_source is True, the 'source'
+        attribute is included in the copy.
+
+        NOTE: When replace is False, and self contains a 'source' attribute,
+              'source' is not replaced even when dict_ has a 'source'
+              attribute, though it may still be merged into a list depending
+              on the value of update_fun.
+        """
+        self.update_all_atts(dict_, Element.copy_attr_consistent, replace,
+                             and_source)
+
+    def update_all_atts_concatenating(self, dict_, replace = True,
+                                      and_source = False):
+        """
+        Updates all attributes from node or dictionary `dict_`.
+
+        Appends the basic attributes ('ids', 'names', 'classes',
+        'dupnames', but not 'source') and then, for all other attributes in
+        dict_, updates the same attribute in self.  When attributes with the
+        same identifier appear in both self and dict_ whose values aren't each
+        lists and replace is True, the values in self are replaced with the
+        values in dict_; if the values from self and dict_ for the given
+        identifier are both of list type, then the two lists are concatenated
+        and the result stored in self; otherwise, the values in self are
+        preserved.  When and_source is True, the 'source' attribute is
+        included in the copy.
+
+        NOTE: When replace is False, and self contains a 'source' attribute,
+              'source' is not replaced even when dict_ has a 'source'
+              attribute, though it may still be merged into a list depending
+              on the value of update_fun.
+        """
+        self.update_all_atts(dict_, Element.copy_attr_concatenate, replace,
+                             and_source)
+
+    def update_all_atts_coercion(self, dict_, replace = True,
+                                 and_source = False):
+        """
+        Updates all attributes from node or dictionary `dict_`.
+
+        Appends the basic attributes ('ids', 'names', 'classes',
+        'dupnames', but not 'source') and then, for all other attributes in
+        dict_, updates the same attribute in self.  When attributes with the
+        same identifier appear in both self and dict_ whose values are both
+        not lists and replace is True, the values in self are replaced with
+        the values in dict_; if either of the values from self and dict_ for
+        the given identifier are of list type, then first any non-lists are
+        converted to 1-element lists and then the two lists are concatenated
+        and the result stored in self; otherwise, the values in self are
+        preserved.  When and_source is True, the 'source' attribute is
+        included in the copy.
+
+        NOTE: When replace is False, and self contains a 'source' attribute,
+              'source' is not replaced even when dict_ has a 'source'
+              attribute, though it may still be merged into a list depending
+              on the value of update_fun.
+        """
+        self.update_all_atts(dict_, Element.copy_attr_coerce, replace,
+                             and_source)
+
+    def update_all_atts_convert(self, dict_, and_source = False):
+        """
+        Updates all attributes from node or dictionary `dict_`.
+
+        Appends the basic attributes ('ids', 'names', 'classes',
+        'dupnames', but not 'source') and then, for all other attributes in
+        dict_, updates the same attribute in self.  When attributes with the
+        same identifier appear in both self and dict_ then first any non-lists
+        are converted to 1-element lists and then the two lists are
+        concatenated and the result stored in self; otherwise, the values in
+        self are preserved.  When and_source is True, the 'source' attribute
+        is included in the copy.
+
+        NOTE: When replace is False, and self contains a 'source' attribute,
+              'source' is not replaced even when dict_ has a 'source'
+              attribute, though it may still be merged into a list depending
+              on the value of update_fun.
+        """
+        self.update_all_atts(dict_, Element.copy_attr_convert,
+                             and_source = and_source)
+
+    def clear(self):
+        self.children = []
+
+    def replace(self, old, new):
+        """Replace one child `Node` with another child or children."""
+        index = self.index(old)
+        if isinstance(new, Node):
+            self.setup_child(new)
+            self[index] = new
+        elif new is not None:
+            self[index:index+1] = new
+
+    def replace_self(self, new):
+        """
+        Replace `self` node with `new`, where `new` is a node or a
+        list of nodes.
+        """
+        update = new
+        if not isinstance(new, Node):
+            # `new` is a list; update first child.
+            try:
+                update = new[0]
+            except IndexError:
+                update = None
+        if isinstance(update, Element):
+            update.update_basic_atts(self)
+        else:
+            # `update` is a Text node or `new` is an empty list.
+            # Assert that we aren't losing any attributes.
+            for att in self.basic_attributes:
+                assert not self[att], \
+                       'Losing "%s" attribute: %s' % (att, self[att])
+        self.parent.replace(self, new)
+
+    def first_child_matching_class(self, childclass, start=0, end=sys.maxsize):
+        """
+        Return the index of the first child whose class exactly matches.
+
+        Parameters:
+
+        - `childclass`: A `Node` subclass to search for, or a tuple of `Node`
+          classes. If a tuple, any of the classes may match.
+        - `start`: Initial index to check.
+        - `end`: Initial index to *not* check.
+        """
+        if not isinstance(childclass, tuple):
+            childclass = (childclass,)
+        for index in range(start, min(len(self), end)):
+            for c in childclass:
+                if isinstance(self[index], c):
+                    return index
+        return None
+
+    def first_child_not_matching_class(self, childclass, start=0,
+                                       end=sys.maxsize):
+        """
+        Return the index of the first child whose class does *not* match.
+
+        Parameters:
+
+        - `childclass`: A `Node` subclass to skip, or a tuple of `Node`
+          classes. If a tuple, none of the classes may match.
+        - `start`: Initial index to check.
+        - `end`: Initial index to *not* check.
+        """
+        if not isinstance(childclass, tuple):
+            childclass = (childclass,)
+        for index in range(start, min(len(self), end)):
+            for c in childclass:
+                if isinstance(self.children[index], c):
+                    break
+            else:
+                return index
+        return None
+
+    def pformat(self, indent='    ', level=0):
+        return ''.join(['%s%s\n' % (indent * level, self.starttag())] +
+                       [child.pformat(indent, level+1)
+                        for child in self.children])
+
+    def copy(self):
+        obj = self.__class__(rawsource=self.rawsource, **self.attributes)
+        obj._document = self._document
+        obj.source = self.source
+        obj.line = self.line
+        return obj
+
+    def deepcopy(self):
+        copy = self.copy()
+        copy.extend([child.deepcopy() for child in self.children])
+        return copy
+
+    def set_class(self, name):
+        """Add a new class to the "classes" attribute."""
+        warnings.warn('docutils.nodes.Element.set_class deprecated; '
+                      "append to Element['classes'] list attribute directly",
+                      DeprecationWarning, stacklevel=2)
+        assert ' ' not in name
+        self['classes'].append(name.lower())
+
+    def note_referenced_by(self, name=None, id=None):
+        """Note that this Element has been referenced by its name
+        `name` or id `id`."""
+        self.referenced = 1
+        # Element.expect_referenced_by_* dictionaries map names or ids
+        # to nodes whose ``referenced`` attribute is set to true as
+        # soon as this node is referenced by the given name or id.
+        # Needed for target propagation.
+        by_name = getattr(self, 'expect_referenced_by_name', {}).get(name)
+        by_id = getattr(self, 'expect_referenced_by_id', {}).get(id)
+        if by_name:
+            assert name is not None
+            by_name.referenced = 1
+        if by_id:
+            assert id is not None
+            by_id.referenced = 1
+
+    @classmethod
+    def is_not_list_attribute(cls, attr):
+        """
+        Returns True if and only if the given attribute is NOT one of the
+        basic list attributes defined for all Elements.
+        """
+        return attr not in cls.list_attributes
+
+    @classmethod
+    def is_not_known_attribute(cls, attr):
+        """
+        Returns True if and only if the given attribute is NOT recognized by
+        this class.
+        """
+        return attr not in cls.known_attributes
+
+
+class TextElement(Element):
+
+    """
+    An element which directly contains text.
+
+    Its children are all `Text` or `Inline` subclass nodes.  You can
+    check whether an element's context is inline simply by checking whether
+    its immediate parent is a `TextElement` instance (including subclasses).
+    This is handy for nodes like `image` that can appear both inline and as
+    standalone body elements.
+
+    If passing children to `__init__()`, make sure to set `text` to
+    ``''`` or some other suitable value.
+    """
+
+    child_text_separator = ''
+    """Separator for child nodes, used by `astext()` method."""
+
+    def __init__(self, rawsource='', text='', *children, **attributes):
+        if text != '':
+            textnode = Text(text)
+            Element.__init__(self, rawsource, textnode, *children,
+                              **attributes)
+        else:
+            Element.__init__(self, rawsource, *children, **attributes)
+
+
+class FixedTextElement(TextElement):
+
+    """An element which directly contains preformatted text."""
+
+    def __init__(self, rawsource='', text='', *children, **attributes):
+        TextElement.__init__(self, rawsource, text, *children, **attributes)
+        self.attributes['xml:space'] = 'preserve'
+
+
+# ========
+#  Mixins
+# ========
+
+class Resolvable(object):
+
+    resolved = 0
+
+
+class BackLinkable(object):
+
+    def add_backref(self, refid):
+        self['backrefs'].append(refid)
+
+
+# ====================
+#  Element Categories
+# ====================
+
+class Root(object):
+    pass
+
+
+class Titular(object):
+    pass
+
+
+class PreBibliographic(object):
+    """Category of Node which may occur before Bibliographic Nodes."""
+
+
+class Bibliographic(object):
+    pass
+
+
+class Decorative(PreBibliographic):
+    pass
+
+
+class Structural(object):
+    pass
+
+
+class Body(object):
+    pass
+
+
+class General(Body):
+    pass
+
+
+class Sequential(Body):
+    """List-like elements."""
+
+
+class Admonition(Body): pass
+
+
+class Special(Body):
+    """Special internal body elements."""
+
+
+class Invisible(PreBibliographic):
+    """Internal elements that don't appear in output."""
+
+
+class Part(object):
+    pass
+
+
+class Inline(object):
+    pass
+
+
+class Referential(Resolvable):
+    pass
+
+
+class Targetable(Resolvable):
+
+    referenced = 0
+
+    indirect_reference_name = None
+    """Holds the whitespace_normalized_name (contains mixed case) of a target.
+    Required for MoinMoin/reST compatibility."""
+
+
+class Labeled(object):
+    """Contains a `label` as its first element."""
+
+
+# ==============
+#  Root Element
+# ==============
+
+def short_title(titlename):
+    titlename = titlename.lower()
+    cn_symbol = "。；，“”（）、？《》"
+    en_symbol = ".,=+*()<>[]{}|/&"
+    spec_symbol = "_:："
+    for i in cn_symbol:
+        titlename = titlename.replace(i, '')
+    for j in en_symbol:
+        titlename = titlename.replace(j, '')
+    for k in spec_symbol:
+        titlename = titlename.replace(k, ' ')
+    titlename = titlename.replace('  ', ' ').replace(' ', '-').replace('"', '')
+
+    return titlename
+
+class document(Root, Structural, Element):
+
+    """
+    The document root element.
+
+    Do not instantiate this class directly; use
+    `docutils.utils.new_document()` instead.
+    """
+
+    def __init__(self, settings, reporter, *args, **kwargs):
+        Element.__init__(self, *args, **kwargs)
+
+        self.current_source = None
+        """Path to or description of the input source being processed."""
+
+        self.current_line = None
+        """Line number (1-based) of `current_source`."""
+
+        self.settings = settings
+        """Runtime settings data record."""
+
+        self.reporter = reporter
+        """System message generator."""
+
+        self.indirect_targets = []
+        """List of indirect target nodes."""
+
+        self.substitution_defs = {}
+        """Mapping of substitution names to substitution_definition nodes."""
+
+        self.substitution_names = {}
+        """Mapping of case-normalized substitution names to case-sensitive
+        names."""
+
+        self.refnames = {}
+        """Mapping of names to lists of referencing nodes."""
+
+        self.refids = {}
+        """Mapping of ids to lists of referencing nodes."""
+
+        self.nameids = {}
+        """Mapping of names to unique id's."""
+
+        self.nametypes = {}
+        """Mapping of names to hyperlink type (boolean: True => explicit,
+        False => implicit."""
+
+        self.ids = {}
+        """Mapping of ids to nodes."""
+
+        self.footnote_refs = {}
+        """Mapping of footnote labels to lists of footnote_reference nodes."""
+
+        self.citation_refs = {}
+        """Mapping of citation labels to lists of citation_reference nodes."""
+
+        self.autofootnotes = []
+        """List of auto-numbered footnote nodes."""
+
+        self.autofootnote_refs = []
+        """List of auto-numbered footnote_reference nodes."""
+
+        self.symbol_footnotes = []
+        """List of symbol footnote nodes."""
+
+        self.symbol_footnote_refs = []
+        """List of symbol footnote_reference nodes."""
+
+        self.footnotes = []
+        """List of manually-numbered footnote nodes."""
+
+        self.citations = []
+        """List of citation nodes."""
+
+        self.autofootnote_start = 1
+        """Initial auto-numbered footnote number."""
+
+        self.symbol_footnote_start = 0
+        """Initial symbol footnote symbol index."""
+
+        self.id_counter = Counter()
+        """Numbers added to otherwise identical IDs."""
+
+        self.parse_messages = []
+        """System messages generated while parsing."""
+
+        self.transform_messages = []
+        """System messages generated while applying transforms."""
+
+        import docutils.transforms
+        self.transformer = docutils.transforms.Transformer(self)
+        """Storage for transforms to be applied to this document."""
+
+        self.include_log = []
+        """The current source's parents (to detect inclusion loops)."""
+
+        self.decoration = None
+        """Document's `decoration` node."""
+
+        self._document = self
+
+    def __getstate__(self):
+        """
+        Return dict with unpicklable references removed.
+        """
+        state = self.__dict__.copy()
+        state['reporter'] = None
+        state['transformer'] = None
+        return state
+
+    def asdom(self, dom=None):
+        """Return a DOM representation of this document."""
+        if dom is None:
+            import xml.dom.minidom as dom
+        domroot = dom.Document()
+        domroot.appendChild(self._dom_node(domroot))
+        return domroot
+
+    def set_id(self, node, msgnode=None, suggested_prefix=''):
+        if node['ids']:
+            # register and check for duplicates
+            for id in node['ids']:
+                self.ids.setdefault(id, node)
+                if self.ids[id] is not node:
+                    msg = self.reporter.severe('Duplicate ID: "%s".' % id)
+                    if msgnode != None:
+                        msgnode += msg
+            return id
+        # generate and set id
+        id_prefix = self.settings.id_prefix
+        auto_id_prefix = self.settings.auto_id_prefix
+        base_id = ''
+        id = ''
+        for name in node['names']:
+            base_id = make_id(name)
+            id = id_prefix + base_id
+            # TODO: allow names starting with numbers if `id_prefix`
+            # is non-empty:  id = make_id(id_prefix + name)
+            if base_id and id not in self.ids:
+                break
+        else:
+            if base_id and auto_id_prefix.endswith('%'):
+                # disambiguate name-derived ID
+                # TODO: remove second condition after announcing change
+                prefix = id + '-'
+            else:
+                prefix = id_prefix + auto_id_prefix
+                if  prefix.endswith('%'):
+                    prefix = '%s%s-' % (prefix[:-1], suggested_prefix
+                                                or make_id(node.tagname))
+            while True:
+                self.id_counter[prefix] += 1
+                id = '%s%d' % (prefix, self.id_counter[prefix])
+                if id not in self.ids:
+                    break
+        flag = 0
+        if node['names']:
+            id = node['names'][0]
+            origin_id = id
+            id = short_title(id)
+            self.id_counter[id] += 1
+            if self.id_counter[id] > 1:
+                id = '{}-{}'.format(id, self.id_counter[id]-1)
+                self.id_counter[id] += 1
+            else:
+                zhcnPattern = re.findall(r'[\u4e00-\u9fa5]',origin_id)
+                if not zhcnPattern and origin_id==origin_id.lower():
+                    flag = 1
+        if flag==1:
+            rep_symbol = "._:"
+            empty_symbol = "()&"
+            for s in rep_symbol:
+                origin_id = origin_id.replace(s,'-')
+            for s in empty_symbol:
+                origin_id = origin_id.replace(s,'')
+            node['ids'].append(origin_id.replace('\"','').replace(" ","-").replace("--","-"))
+        else:
+            node['ids'].append(id)
+        self.ids[id] = node
+        return id
+
+    def set_name_id_map(self, node, id, msgnode=None, explicit=None):
+        """
+        `self.nameids` maps names to IDs, while `self.nametypes` maps names to
+        booleans representing hyperlink type (True==explicit,
+        False==implicit).  This method updates the mappings.
+
+        The following state transition table shows how `self.nameids` ("ids")
+        and `self.nametypes` ("types") change with new input (a call to this
+        method), and what actions are performed ("implicit"-type system
+        messages are INFO/1, and "explicit"-type system messages are ERROR/3):
+
+        ====  =====  ========  ========  =======  ====  =====  =====
+         Old State    Input          Action        New State   Notes
+        -----------  --------  -----------------  -----------  -----
+        ids   types  new type  sys.msg.  dupname  ids   types
+        ====  =====  ========  ========  =======  ====  =====  =====
+        -     -      explicit  -         -        new   True
+        -     -      implicit  -         -        new   False
+        None  False  explicit  -         -        new   True
+        old   False  explicit  implicit  old      new   True
+        None  True   explicit  explicit  new      None  True
+        old   True   explicit  explicit  new,old  None  True   [#]_
+        None  False  implicit  implicit  new      None  False
+        old   False  implicit  implicit  new,old  None  False
+        None  True   implicit  implicit  new      None  True
+        old   True   implicit  implicit  new      old   True
+        ====  =====  ========  ========  =======  ====  =====  =====
+
+        .. [#] Do not clear the name-to-id map or invalidate the old target if
+           both old and new targets are external and refer to identical URIs.
+           The new target is invalidated regardless.
+        """
+        for name in node['names']:
+            if name in self.nameids:
+                self.set_duplicate_name_id(node, id, name, msgnode, explicit)
+            else:
+                self.nameids[name] = id
+                self.nametypes[name] = explicit
+
+    def set_duplicate_name_id(self, node, id, name, msgnode, explicit):
+        old_id = self.nameids[name]
+        old_explicit = self.nametypes[name]
+        self.nametypes[name] = old_explicit or explicit
+        if explicit:
+            if old_explicit:
+                level = 2
+                if old_id is not None:
+                    old_node = self.ids[old_id]
+                    if 'refuri' in node:
+                        refuri = node['refuri']
+                        if old_node['names'] \
+                               and 'refuri' in old_node \
+                               and old_node['refuri'] == refuri:
+                            level = 1   # just inform if refuri's identical
+                    if level > 1:
+                        dupname(old_node, name)
+                        self.nameids[name] = None
+                msg = self.reporter.system_message(
+                    level, 'Duplicate explicit target name: "%s".' % name,
+                    backrefs=[id], base_node=node)
+                if msgnode != None:
+                    msgnode += msg
+                dupname(node, name)
+            else:
+                self.nameids[name] = id
+                if old_id is not None:
+                    old_node = self.ids[old_id]
+                    dupname(old_node, name)
+        else:
+            if old_id is not None and not old_explicit:
+                self.nameids[name] = None
+                old_node = self.ids[old_id]
+                dupname(old_node, name)
+            dupname(node, name)
+        if not explicit or (not old_explicit and old_id is not None):
+            msg = self.reporter.info(
+                'Duplicate implicit target name: "%s".' % name,
+                backrefs=[id], base_node=node)
+            if msgnode != None:
+                msgnode += msg
+
+    def has_name(self, name):
+        return name in self.nameids
+
+    # "note" here is an imperative verb: "take note of".
+    def note_implicit_target(self, target, msgnode=None):
+        id = self.set_id(target, msgnode)
+        self.set_name_id_map(target, id, msgnode, explicit=None)
+
+    def note_explicit_target(self, target, msgnode=None):
+        id = self.set_id(target, msgnode)
+        self.set_name_id_map(target, id, msgnode, explicit=True)
+
+    def note_refname(self, node):
+        self.refnames.setdefault(node['refname'], []).append(node)
+
+    def note_refid(self, node):
+        self.refids.setdefault(node['refid'], []).append(node)
+
+    def note_indirect_target(self, target):
+        self.indirect_targets.append(target)
+        if target['names']:
+            self.note_refname(target)
+
+    def note_anonymous_target(self, target):
+        self.set_id(target)
+
+    def note_autofootnote(self, footnote):
+        self.set_id(footnote)
+        self.autofootnotes.append(footnote)
+
+    def note_autofootnote_ref(self, ref):
+        self.set_id(ref)
+        self.autofootnote_refs.append(ref)
+
+    def note_symbol_footnote(self, footnote):
+        self.set_id(footnote)
+        self.symbol_footnotes.append(footnote)
+
+    def note_symbol_footnote_ref(self, ref):
+        self.set_id(ref)
+        self.symbol_footnote_refs.append(ref)
+
+    def note_footnote(self, footnote):
+        self.set_id(footnote)
+        self.footnotes.append(footnote)
+
+    def note_footnote_ref(self, ref):
+        self.set_id(ref)
+        self.footnote_refs.setdefault(ref['refname'], []).append(ref)
+        self.note_refname(ref)
+
+    def note_citation(self, citation):
+        self.citations.append(citation)
+
+    def note_citation_ref(self, ref):
+        self.set_id(ref)
+        self.citation_refs.setdefault(ref['refname'], []).append(ref)
+        self.note_refname(ref)
+
+    def note_substitution_def(self, subdef, def_name, msgnode=None):
+        name = whitespace_normalize_name(def_name)
+        if name in self.substitution_defs:
+            msg = self.reporter.error(
+                  'Duplicate substitution definition name: "%s".' % name,
+                  base_node=subdef)
+            if msgnode != None:
+                msgnode += msg
+            oldnode = self.substitution_defs[name]
+            dupname(oldnode, name)
+        # keep only the last definition:
+        self.substitution_defs[name] = subdef
+        # case-insensitive mapping:
+        self.substitution_names[fully_normalize_name(name)] = name
+
+    def note_substitution_ref(self, subref, refname):
+        subref['refname'] = whitespace_normalize_name(refname)
+
+    def note_pending(self, pending, priority=None):
+        self.transformer.add_pending(pending, priority)
+
+    def note_parse_message(self, message):
+        self.parse_messages.append(message)
+
+    def note_transform_message(self, message):
+        self.transform_messages.append(message)
+
+    def note_source(self, source, offset):
+        self.current_source = source
+        if offset is None:
+            self.current_line = offset
+        else:
+            self.current_line = offset + 1
+
+    def copy(self):
+        obj = self.__class__(self.settings, self.reporter,
+                              **self.attributes)
+        obj.source = self.source
+        obj.line = self.line
+        return obj
+
+    def get_decoration(self):
+        if not self.decoration:
+            self.decoration = decoration()
+            index = self.first_child_not_matching_class(Titular)
+            if index is None:
+                self.append(self.decoration)
+            else:
+                self.insert(index, self.decoration)
+        return self.decoration
+
+
+# ================
+#  Title Elements
+# ================
+
+class title(Titular, PreBibliographic, TextElement): pass
+class subtitle(Titular, PreBibliographic, TextElement): pass
+class rubric(Titular, TextElement): pass
+
+
+# ========================
+#  Bibliographic Elements
+# ========================
+
+class docinfo(Bibliographic, Element): pass
+class author(Bibliographic, TextElement): pass
+class authors(Bibliographic, Element): pass
+class organization(Bibliographic, TextElement): pass
+class address(Bibliographic, FixedTextElement): pass
+class contact(Bibliographic, TextElement): pass
+class version(Bibliographic, TextElement): pass
+class revision(Bibliographic, TextElement): pass
+class status(Bibliographic, TextElement): pass
+class date(Bibliographic, TextElement): pass
+class copyright(Bibliographic, TextElement): pass
+
+
+# =====================
+#  Decorative Elements
+# =====================
+
+class decoration(Decorative, Element):
+
+    def get_header(self):
+        if not len(self.children) or not isinstance(self.children[0], header):
+            self.insert(0, header())
+        return self.children[0]
+
+    def get_footer(self):
+        if not len(self.children) or not isinstance(self.children[-1], footer):
+            self.append(footer())
+        return self.children[-1]
+
+
+class header(Decorative, Element): pass
+class footer(Decorative, Element): pass
+
+
+# =====================
+#  Structural Elements
+# =====================
+
+class section(Structural, Element): pass
+
+
+class topic(Structural, Element):
+
+    """
+    Topics are terminal, "leaf" mini-sections, like block quotes with titles,
+    or textual figures.  A topic is just like a section, except that it has no
+    subsections, and it doesn't have to conform to section placement rules.
+
+    Topics are allowed wherever body elements (list, table, etc.) are allowed,
+    but only at the top level of a section or document.  Topics cannot nest
+    inside topics, sidebars, or body elements; you can't have a topic inside a
+    table, list, block quote, etc.
+    """
+
+
+class sidebar(Structural, Element):
+
+    """
+    Sidebars are like miniature, parallel documents that occur inside other
+    documents, providing related or reference material.  A sidebar is
+    typically offset by a border and "floats" to the side of the page; the
+    document's main text may flow around it.  Sidebars can also be likened to
+    super-footnotes; their content is outside of the flow of the document's
+    main text.
+
+    Sidebars are allowed wherever body elements (list, table, etc.) are
+    allowed, but only at the top level of a section or document.  Sidebars
+    cannot nest inside sidebars, topics, or body elements; you can't have a
+    sidebar inside a table, list, block quote, etc.
+    """
+
+
+class transition(Structural, Element): pass
+
+
+# ===============
+#  Body Elements
+# ===============
+
+class paragraph(General, TextElement): pass
+class compound(General, Element): pass
+class container(General, Element): pass
+class bullet_list(Sequential, Element): pass
+class enumerated_list(Sequential, Element): pass
+class list_item(Part, Element): pass
+class definition_list(Sequential, Element): pass
+class definition_list_item(Part, Element): pass
+class term(Part, TextElement): pass
+class classifier(Part, TextElement): pass
+class definition(Part, Element): pass
+class field_list(Sequential, Element): pass
+class field(Part, Element): pass
+class field_name(Part, TextElement): pass
+class field_body(Part, Element): pass
+
+
+class option(Part, Element):
+
+    child_text_separator = ''
+
+
+class option_argument(Part, TextElement):
+
+    def astext(self):
+        return self.get('delimiter', ' ') + TextElement.astext(self)
+
+
+class option_group(Part, Element):
+
+    child_text_separator = ', '
+
+
+class option_list(Sequential, Element): pass
+
+
+class option_list_item(Part, Element):
+
+    child_text_separator = '  '
+
+
+class option_string(Part, TextElement): pass
+class description(Part, Element): pass
+class literal_block(General, FixedTextElement): pass
+class doctest_block(General, FixedTextElement): pass
+class math_block(General, FixedTextElement): pass
+class line_block(General, Element): pass
+
+
+class line(Part, TextElement):
+
+    indent = None
+
+
+class block_quote(General, Element): pass
+class attribution(Part, TextElement): pass
+class attention(Admonition, Element): pass
+class caution(Admonition, Element): pass
+class danger(Admonition, Element): pass
+class error(Admonition, Element): pass
+class important(Admonition, Element): pass
+class note(Admonition, Element): pass
+class tip(Admonition, Element): pass
+class hint(Admonition, Element): pass
+class warning(Admonition, Element): pass
+class admonition(Admonition, Element): pass
+class comment(Special, Invisible, FixedTextElement): pass
+class substitution_definition(Special, Invisible, TextElement): pass
+class target(Special, Invisible, Inline, TextElement, Targetable): pass
+class footnote(General, BackLinkable, Element, Labeled, Targetable): pass
+class citation(General, BackLinkable, Element, Labeled, Targetable): pass
+class label(Part, TextElement): pass
+class figure(General, Element): pass
+class caption(Part, TextElement): pass
+class legend(Part, Element): pass
+class table(General, Element): pass
+class tgroup(Part, Element): pass
+class colspec(Part, Element): pass
+class thead(Part, Element): pass
+class tbody(Part, Element): pass
+class row(Part, Element): pass
+class entry(Part, Element): pass
+
+
+class system_message(Special, BackLinkable, PreBibliographic, Element):
+
+    """
+    System message element.
+
+    Do not instantiate this class directly; use
+    ``document.reporter.info/warning/error/severe()`` instead.
+    """
+
+    def __init__(self, message=None, *children, **attributes):
+        rawsource = attributes.pop('rawsource', '')
+        if message:
+            p = paragraph('', message)
+            children = (p,) + children
+        try:
+            Element.__init__(self, rawsource, *children, **attributes)
+        except:
+            print('system_message: children=%r' % (children,))
+            raise
+
+    def astext(self):
+        line = self.get('line', '')
+        return u'%s:%s: (%s/%s) %s' % (self['source'], line, self['type'],
+                                       self['level'], Element.astext(self))
+
+
+class pending(Special, Invisible, Element):
+
+    """
+    The "pending" element is used to encapsulate a pending operation: the
+    operation (transform), the point at which to apply it, and any data it
+    requires.  Only the pending operation's location within the document is
+    stored in the public document tree (by the "pending" object itself); the
+    operation and its data are stored in the "pending" object's internal
+    instance attributes.
+
+    For example, say you want a table of contents in your reStructuredText
+    document.  The easiest way to specify where to put it is from within the
+    document, with a directive::
+
+        .. contents::
+
+    But the "contents" directive can't do its work until the entire document
+    has been parsed and possibly transformed to some extent.  So the directive
+    code leaves a placeholder behind that will trigger the second phase of its
+    processing, something like this::
+
+        <pending ...public attributes...> + internal attributes
+
+    Use `document.note_pending()` so that the
+    `docutils.transforms.Transformer` stage of processing can run all pending
+    transforms.
+    """
+
+    def __init__(self, transform, details=None,
+                 rawsource='', *children, **attributes):
+        Element.__init__(self, rawsource, *children, **attributes)
+
+        self.transform = transform
+        """The `docutils.transforms.Transform` class implementing the pending
+        operation."""
+
+        self.details = details or {}
+        """Detail data (dictionary) required by the pending operation."""
+
+    def pformat(self, indent='    ', level=0):
+        internals = [
+              '.. internal attributes:',
+              '     .transform: %s.%s' % (self.transform.__module__,
+                                          self.transform.__name__),
+              '     .details:']
+        details = sorted(self.details.items())
+        for key, value in details:
+            if isinstance(value, Node):
+                internals.append('%7s%s:' % ('', key))
+                internals.extend(['%9s%s' % ('', line)
+                                  for line in value.pformat().splitlines()])
+            elif value and isinstance(value, list) \
+                  and isinstance(value[0], Node):
+                internals.append('%7s%s:' % ('', key))
+                for v in value:
+                    internals.extend(['%9s%s' % ('', line)
+                                      for line in v.pformat().splitlines()])
+            else:
+                internals.append('%7s%s: %r' % ('', key, value))
+        return (Element.pformat(self, indent, level)
+                + ''.join([('    %s%s\n' % (indent * level, line))
+                           for line in internals]))
+
+    def copy(self):
+        obj = self.__class__(self.transform, self.details, self.rawsource,
+                              **self.attributes)
+        obj._document = self._document
+        obj.source = self.source
+        obj.line = self.line
+        return obj
+
+
+class raw(Special, Inline, PreBibliographic, FixedTextElement):
+
+    """
+    Raw data that is to be passed untouched to the Writer.
+    """
+
+    pass
+
+
+# =================
+#  Inline Elements
+# =================
+
+class emphasis(Inline, TextElement): pass
+class strong(Inline, TextElement): pass
+class literal(Inline, TextElement): pass
+class reference(General, Inline, Referential, TextElement): pass
+class footnote_reference(Inline, Referential, TextElement): pass
+class citation_reference(Inline, Referential, TextElement): pass
+class substitution_reference(Inline, TextElement): pass
+class title_reference(Inline, TextElement): pass
+class abbreviation(Inline, TextElement): pass
+class acronym(Inline, TextElement): pass
+class superscript(Inline, TextElement): pass
+class subscript(Inline, TextElement): pass
+class math(Inline, TextElement): pass
+
+
+class image(General, Inline, Element):
+
+    def astext(self):
+        return self.get('alt', '')
+
+
+class inline(Inline, TextElement): pass
+class problematic(Inline, TextElement): pass
+class generated(Inline, TextElement): pass
+
+
+# ========================================
+#  Auxiliary Classes, Functions, and Data
+# ========================================
+
+node_class_names = """
+    Text
+    abbreviation acronym address admonition attention attribution author
+        authors
+    block_quote bullet_list
+    caption caution citation citation_reference classifier colspec comment
+        compound contact container copyright
+    danger date decoration definition definition_list definition_list_item
+        description docinfo doctest_block document
+    emphasis entry enumerated_list error
+    field field_body field_list field_name figure footer
+        footnote footnote_reference
+    generated
+    header hint
+    image important inline
+    label legend line line_block list_item literal literal_block
+    math math_block
+    note
+    option option_argument option_group option_list option_list_item
+        option_string organization
+    paragraph pending problematic
+    raw reference revision row rubric
+    section sidebar status strong subscript substitution_definition
+        substitution_reference subtitle superscript system_message
+    table target tbody term tgroup thead tip title title_reference topic
+        transition
+    version
+    warning""".split()
+"""A list of names of all concrete Node subclasses."""
+
+
+class NodeVisitor(object):
+
+    """
+    "Visitor" pattern [GoF95]_ abstract superclass implementation for
+    document tree traversals.
+
+    Each node class has corresponding methods, doing nothing by
+    default; override individual methods for specific and useful
+    behaviour.  The `dispatch_visit()` method is called by
+    `Node.walk()` upon entering a node.  `Node.walkabout()` also calls
+    the `dispatch_departure()` method before exiting a node.
+
+    The dispatch methods call "``visit_`` + node class name" or
+    "``depart_`` + node class name", resp.
+
+    This is a base class for visitors whose ``visit_...`` & ``depart_...``
+    methods should be implemented for *all* node types encountered (such as
+    for `docutils.writers.Writer` subclasses).  Unimplemented methods will
+    raise exceptions.
+
+    For sparse traversals, where only certain node types are of interest, use
+    subclass `SparseNodeVisitor` instead.  When (mostly or entirely) uniform
+    processing is desired, subclass `GenericNodeVisitor`.
+
+    .. [GoF95] Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of
+       Reusable Object-Oriented Software*. Addison-Wesley, Reading, MA, USA,
+       1995.
+    """
+
+    optional = ()
+    """
+    Tuple containing node class names (as strings).
+
+    No exception will be raised if writers do not implement visit
+    or departure functions for these node classes.
+
+    Used to ensure transitional compatibility with existing 3rd-party writers.
+    """
+
+    def __init__(self, document):
+        self.document = document
+
+    def dispatch_visit(self, node):
+        """
+        Call self."``visit_`` + node class name" with `node` as
+        parameter.  If the ``visit_...`` method does not exist, call
+        self.unknown_visit.
+        """
+        node_name = node.__class__.__name__
+        method = getattr(self, 'visit_' + node_name, self.unknown_visit)
+        self.document.reporter.debug(
+            'docutils.nodes.NodeVisitor.dispatch_visit calling %s for %s'
+            % (method.__name__, node_name))
+        return method(node)
+
+    def dispatch_departure(self, node):
+        """
+        Call self."``depart_`` + node class name" with `node` as
+        parameter.  If the ``depart_...`` method does not exist, call
+        self.unknown_departure.
+        """
+        node_name = node.__class__.__name__
+        method = getattr(self, 'depart_' + node_name, self.unknown_departure)
+        self.document.reporter.debug(
+            'docutils.nodes.NodeVisitor.dispatch_departure calling %s for %s'
+            % (method.__name__, node_name))
+        return method(node)
+
+    def unknown_visit(self, node):
+        """
+        Called when entering unknown `Node` types.
+
+        Raise an exception unless overridden.
+        """
+        if  (self.document.settings.strict_visitor
+             or node.__class__.__name__ not in self.optional):
+            raise NotImplementedError(
+                '%s visiting unknown node type: %s'
+                % (self.__class__, node.__class__.__name__))
+
+    def unknown_departure(self, node):
+        """
+        Called before exiting unknown `Node` types.
+
+        Raise exception unless overridden.
+        """
+        if  (self.document.settings.strict_visitor
+             or node.__class__.__name__ not in self.optional):
+            raise NotImplementedError(
+                '%s departing unknown node type: %s'
+                % (self.__class__, node.__class__.__name__))
+
+
+class SparseNodeVisitor(NodeVisitor):
+
+    """
+    Base class for sparse traversals, where only certain node types are of
+    interest.  When ``visit_...`` & ``depart_...`` methods should be
+    implemented for *all* node types (such as for `docutils.writers.Writer`
+    subclasses), subclass `NodeVisitor` instead.
+    """
+
+
+class GenericNodeVisitor(NodeVisitor):
+
+    """
+    Generic "Visitor" abstract superclass, for simple traversals.
+
+    Unless overridden, each ``visit_...`` method calls `default_visit()`, and
+    each ``depart_...`` method (when using `Node.walkabout()`) calls
+    `default_departure()`. `default_visit()` (and `default_departure()`) must
+    be overridden in subclasses.
+
+    Define fully generic visitors by overriding `default_visit()` (and
+    `default_departure()`) only. Define semi-generic visitors by overriding
+    individual ``visit_...()`` (and ``depart_...()``) methods also.
+
+    `NodeVisitor.unknown_visit()` (`NodeVisitor.unknown_departure()`) should
+    be overridden for default behavior.
+    """
+
+    def default_visit(self, node):
+        """Override for generic, uniform traversals."""
+        raise NotImplementedError
+
+    def default_departure(self, node):
+        """Override for generic, uniform traversals."""
+        raise NotImplementedError
+
+def _call_default_visit(self, node):
+    self.default_visit(node)
+
+def _call_default_departure(self, node):
+    self.default_departure(node)
+
+def _nop(self, node):
+    pass
+
+def _add_node_class_names(names):
+    """Save typing with dynamic assignments:"""
+    for _name in names:
+        setattr(GenericNodeVisitor, "visit_" + _name, _call_default_visit)
+        setattr(GenericNodeVisitor, "depart_" + _name, _call_default_departure)
+        setattr(SparseNodeVisitor, 'visit_' + _name, _nop)
+        setattr(SparseNodeVisitor, 'depart_' + _name, _nop)
+
+_add_node_class_names(node_class_names)
+
+
+class TreeCopyVisitor(GenericNodeVisitor):
+
+    """
+    Make a complete copy of a tree or branch, including element attributes.
+    """
+
+    def __init__(self, document):
+        GenericNodeVisitor.__init__(self, document)
+        self.parent_stack = []
+        self.parent = []
+
+    def get_tree_copy(self):
+        return self.parent[0]
+
+    def default_visit(self, node):
+        """Copy the current node, and make it the new acting parent."""
+        newnode = node.copy()
+        self.parent.append(newnode)
+        self.parent_stack.append(self.parent)
+        self.parent = newnode
+
+    def default_departure(self, node):
+        """Restore the previous acting parent."""
+        self.parent = self.parent_stack.pop()
+
+
+class TreePruningException(Exception):
+
+    """
+    Base class for `NodeVisitor`-related tree pruning exceptions.
+
+    Raise subclasses from within ``visit_...`` or ``depart_...`` methods
+    called from `Node.walk()` and `Node.walkabout()` tree traversals to prune
+    the tree traversed.
+    """
+
+    pass
+
+
+class SkipChildren(TreePruningException):
+
+    """
+    Do not visit any children of the current node.  The current node's
+    siblings and ``depart_...`` method are not affected.
+    """
+
+    pass
+
+
+class SkipSiblings(TreePruningException):
+
+    """
+    Do not visit any more siblings (to the right) of the current node.  The
+    current node's children and its ``depart_...`` method are not affected.
+    """
+
+    pass
+
+
+class SkipNode(TreePruningException):
+
+    """
+    Do not visit the current node's children, and do not call the current
+    node's ``depart_...`` method.
+    """
+
+    pass
+
+
+class SkipDeparture(TreePruningException):
+
+    """
+    Do not call the current node's ``depart_...`` method.  The current node's
+    children and siblings are not affected.
+    """
+
+    pass
+
+
+class NodeFound(TreePruningException):
+
+    """
+    Raise to indicate that the target of a search has been found.  This
+    exception must be caught by the client; it is not caught by the traversal
+    code.
+    """
+
+    pass
+
+
+class StopTraversal(TreePruningException):
+
+    """
+    Stop the traversal all together.  The current node's ``depart_...`` method
+    is not affected.  The parent nodes ``depart_...`` methods are also called
+    as usual.  No other nodes are visited.  This is an alternative to
+    NodeFound that does not cause exception handling to trickle up to the
+    caller.
+    """
+
+    pass
+
+
+def make_id(string):
+    """
+    Convert `string` into an identifier and return it.
+
+    Docutils identifiers will conform to the regular expression
+    ``[a-z](-?[a-z0-9]+)*``.  For CSS compatibility, identifiers (the "class"
+    and "id" attributes) should have no underscores, colons, or periods.
+    Hyphens may be used.
+
+    - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:
+
+          ID and NAME tokens must begin with a letter ([A-Za-z]) and may be
+          followed by any number of letters, digits ([0-9]), hyphens ("-"),
+          underscores ("_"), colons (":"), and periods (".").
+
+    - However the `CSS1 spec`_ defines identifiers based on the "name" token,
+      a tighter interpretation ("flex" tokenizer notation; "latin1" and
+      "escape" 8-bit characters have been replaced with entities)::
+
+          unicode     \\[0-9a-f]{1,4}
+          latin1      [&iexcl;-&yuml;]
+          escape      {unicode}|\\[ -~&iexcl;-&yuml;]
+          nmchar      [-a-z0-9]|{latin1}|{escape}
+          name        {nmchar}+
+
+    The CSS1 "nmchar" rule does not include underscores ("_"), colons (":"),
+    or periods ("."), therefore "class" and "id" attributes should not contain
+    these characters. They should be replaced with hyphens ("-"). Combined
+    with HTML's requirements (the first character must be a letter; no
+    "unicode", "latin1", or "escape" characters), this results in the
+    ``[a-z](-?[a-z0-9]+)*`` pattern.
+
+    .. _HTML 4.01 spec: http://www.w3.org/TR/html401
+    .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
+    """
+    id = string.lower()
+    if not isinstance(id, unicode):
+        id = id.decode()
+    id = id.translate(_non_id_translate_digraphs)
+    id = id.translate(_non_id_translate)
+    # get rid of non-ascii characters.
+    # 'ascii' lowercase to prevent problems with turkish locale.
+    id = unicodedata.normalize('NFKD', id).\
+         encode('ascii', 'ignore').decode('ascii')
+    # shrink runs of whitespace and replace by hyphen
+    id = _non_id_chars.sub('-', ' '.join(id.split()))
+    id = _non_id_at_ends.sub('', id)
+    return str(id)
+
+_non_id_chars = re.compile('[^a-z0-9]+')
+_non_id_at_ends = re.compile('^[-0-9]+|-+$')
+_non_id_translate = {
+    0x00f8: u'o',       # o with stroke
+    0x0111: u'd',       # d with stroke
+    0x0127: u'h',       # h with stroke
+    0x0131: u'i',       # dotless i
+    0x0142: u'l',       # l with stroke
+    0x0167: u't',       # t with stroke
+    0x0180: u'b',       # b with stroke
+    0x0183: u'b',       # b with topbar
+    0x0188: u'c',       # c with hook
+    0x018c: u'd',       # d with topbar
+    0x0192: u'f',       # f with hook
+    0x0199: u'k',       # k with hook
+    0x019a: u'l',       # l with bar
+    0x019e: u'n',       # n with long right leg
+    0x01a5: u'p',       # p with hook
+    0x01ab: u't',       # t with palatal hook
+    0x01ad: u't',       # t with hook
+    0x01b4: u'y',       # y with hook
+    0x01b6: u'z',       # z with stroke
+    0x01e5: u'g',       # g with stroke
+    0x0225: u'z',       # z with hook
+    0x0234: u'l',       # l with curl
+    0x0235: u'n',       # n with curl
+    0x0236: u't',       # t with curl
+    0x0237: u'j',       # dotless j
+    0x023c: u'c',       # c with stroke
+    0x023f: u's',       # s with swash tail
+    0x0240: u'z',       # z with swash tail
+    0x0247: u'e',       # e with stroke
+    0x0249: u'j',       # j with stroke
+    0x024b: u'q',       # q with hook tail
+    0x024d: u'r',       # r with stroke
+    0x024f: u'y',       # y with stroke
+}
+_non_id_translate_digraphs = {
+    0x00df: u'sz',      # ligature sz
+    0x00e6: u'ae',      # ae
+    0x0153: u'oe',      # ligature oe
+    0x0238: u'db',      # db digraph
+    0x0239: u'qp',      # qp digraph
+}
+
+def dupname(node, name):
+    # node['dupnames'].append(name)
+    # node['names'].remove(name)
+    # # Assume that this method is referenced, even though it isn't; we
+    # # don't want to throw unnecessary system_messages.
+    # node.referenced = 1
+    node['dupnames'].append(name)
+    if node['names']:
+        node['names'].remove(name)
+    node.referenced = 1
+
+def fully_normalize_name(name):
+    """Return a case- and whitespace-normalized name."""
+    return ' '.join(name.lower().split())
+
+def whitespace_normalize_name(name):
+    """Return a whitespace-normalized name."""
+    return ' '.join(name.split())
+
+def serial_escape(value):
+    """Escape string values that are elements of a list, for serialization."""
+    return value.replace('\\', r'\\').replace(' ', r'\ ')
+
+def pseudo_quoteattr(value):
+    """Quote attributes for pseudo-xml"""
+    return '"%s"' % value
+
+# 
+#
+# Local Variables:
+# indent-tabs-mode: nil
+# sentence-end-double-space: t
+# fill-column: 78
+# End:
diff --git a/tools/generate_html/run.py b/tools/generate_html/run.py
index b8e69d314b5182938d3de95f953c35e4debaa741..fab636020dcc6d17c890fb70ea9fb757f91eb38a 100644
--- a/tools/generate_html/run.py
+++ b/tools/generate_html/run.py
@@ -556,16 +556,16 @@ if __name__ == "__main__":
                     static_path_css = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/css/theme.css")[0]
                     static_path_js = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/js/theme.js")[0]
                     static_path_jquery = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/jquery.js")[0]
-                    static_path_underscore = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/underscore.js")[0]
-                    static_path_jquery_ = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/jquery-3.5.1.js")[0]
-                    static_path_underscore_ = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/underscore-1.13.1.js")
-                    static_path_underscore_ = static_path_underscore_[0]
+                    # static_path_underscore = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/underscore.js")[0]
+                    # static_path_jquery_ = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/jquery-3.5.1.js")[0]
+                    # static_path_underscore_ = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/underscore-1.13.1.js")
+                    # static_path_underscore_ = static_path_underscore_[0]
 
                     static_path_css_badge = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/css/badge_only.css")[0]
                     static_path_js_badge = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/js/badge_only.js")[0]
-                    static_path_js_html5p = \
-                    glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/js/html5shiv-printshiv.min.js")[0]
-                    static_path_js_html5 = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/js/html5shiv.min.js")[0]
+                    # static_path_js_html5p = \
+                    # glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/js/html5shiv-printshiv.min.js")[0]
+                    # static_path_js_html5 = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/js/html5shiv.min.js")[0]
 
                     static_path_version = glob.glob(f"{output_path}/{out_name}/{lg}/*/_static/js/")[0]
                     static_path_version = os.path.join(static_path_version, "version.json")
@@ -602,28 +602,28 @@ if __name__ == "__main__":
                     if os.path.exists(static_path_jquery):
                         os.remove(static_path_jquery)
                     shutil.copy(static_path_new_jquery, static_path_jquery)
-                    if os.path.exists(static_path_underscore):
-                        os.remove(static_path_underscore)
-                    shutil.copy(static_path_new_underscore, static_path_underscore)
-                    if os.path.exists(static_path_jquery):
-                        os.remove(static_path_jquery_)
-                    if os.path.exists(static_path_underscore_):
-                        os.remove(static_path_underscore_)
+                    # if os.path.exists(static_path_underscore):
+                    #     os.remove(static_path_underscore)
+                    # shutil.copy(static_path_new_underscore, static_path_underscore)
+                    # if os.path.exists(static_path_jquery):
+                    #     os.remove(static_path_jquery_)
+                    # if os.path.exists(static_path_underscore_):
+                    #     os.remove(static_path_underscore_)
                     if os.path.exists(static_path_css_badge):
                         os.remove(static_path_css_badge)
                     if os.path.exists(static_path_js_badge):
                         os.remove(static_path_js_badge)
-                    if os.path.exists(static_path_js_html5p):
-                        os.remove(static_path_js_html5p)
-                    if os.path.exists(static_path_js_html5):
-                        os.remove(static_path_js_html5)
+                    # if os.path.exists(static_path_js_html5p):
+                    #     os.remove(static_path_js_html5p)
+                    # if os.path.exists(static_path_js_html5):
+                    #     os.remove(static_path_js_html5)
 
                 # pylint: disable=W0702
                 # pylint: disable=W0703
                 except Exception as e:
                     print(f'替换{out_name}下{lg}样式文件失败!\n{e}')
                     continue
-        print(f'替换样式文件成功!')
+        print(f'替换样式结束!')
     except (KeyboardInterrupt, SystemExit):
         print("程序即将终止....")
         time.sleep(1)
diff --git a/tutorials/requirements.txt b/tutorials/requirements.txt
index 47b8077243ba594715dc7c9b48af099c1196b8a4..5db37a529c6e31e1659f885dbf16752c0fcdfa17 100644
--- a/tutorials/requirements.txt
+++ b/tutorials/requirements.txt
@@ -1,7 +1,7 @@
-sphinx == 4.4.0
-docutils == 0.17.1
-myst-parser == 0.18.1
-sphinx_rtd_theme == 1.0.0
+sphinx == 7.0.1
+docutils == 0.20.1
+myst-parser == 2.0.0
+sphinx_rtd_theme == 3.0.0
 numpy
 nbsphinx == 0.8.11
 IPython