code: def _resolve_toctree(
      env: BuildEnvironment,
      docname: str,
      builder: Builder,
      toctree: addnodes.toctree,
      *,
      prune: bool = True,
      maxdepth: int = 0,
      titles_only: bool = False,
      collapse: bool = False,
      includehidden: bool = False,
  ) -> Element | None:
      """Resolve a *toctree* node into individual bullet lists with titles
      as items, returning None (if no containing titles are found) or
      a new node.
  
      If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0,
      to the value of the *maxdepth* option on the *toctree* node.
      If *titles_only* is True, only toplevel document titles will be in the
      resulting tree.
      If *collapse* is True, all branches not containing docname will
      be collapsed.
      """
      if toctree.get("hidden", False) and not includehidden:
          return None
  
      # For reading the following two helper function, it is useful to keep
      # in mind the node structure of a toctree (using HTML-like node names
      # for brevity):
      #
      # <ul>
      #   <li>
      #     <p><a></p>
      #     <p><a></p>
      #     ...
      #     <ul>
      #       ...
      #     </ul>
      #   </li>
      # </ul>
      #
      # The transformation is made in two passes in order to avoid
      # interactions between marking and pruning the tree (see bug #1046).
  
      toctree_ancestors = _get_toctree_ancestors(
          env.toctree_includes, docname
      )
      included = Matcher(env.config.include_patterns)
      excluded = Matcher(env.config.exclude_patterns)
  
      maxdepth = maxdepth or toctree.get("maxdepth", -1)
      if not titles_only and toctree.get("titlesonly", False):
          titles_only = True
      if not includehidden and toctree.get("includehidden", False):
          includehidden = True
  
      tocentries = _entries_from_toctree(
          env,
          prune,
          titles_only,
          collapse,
          includehidden,
          builder.tags,
          toctree_ancestors,
          included,
          excluded,
          toctree,
          [],
      )
      if not tocentries:
          return None
  
      newnode = addnodes.compact_paragraph("", "")
      if caption := toctree.attributes.get("caption"):
          caption_node = nodes.title(
              caption, "", *[nodes.Text(caption)]
          )
          caption_node.line = toctree.line
          caption_node.source = toctree.source
          caption_node.rawsource = toctree["rawcaption"]
          if hasattr(toctree, "uid"):
              # move uid to caption_node to translate it
              caption_node.uid = toctree.uid  # type: ignore[attr-defined]
              del toctree.uid
          newnode.append(caption_node)
      newnode.extend(tocentries)
      newnode["toctree"] = True
  
      # prune the tree to maxdepth, also set toc depth and current classes
      _toctree_add_classes(newnode, 1, docname)
      newnode = _toctree_copy(
          newnode, 1, maxdepth if prune else 0, collapse, builder.tags
      )
  
      if (
          isinstance(newnode[-1], nodes.Element)
          and len(newnode[-1]) == 0
      ):  # No titles found
          return None
  
      # set the target paths in the toctrees (they are not known at TOC
      # generation time)
      for refnode in newnode.findall(nodes.reference):
          if url_re.match(refnode["refuri"]) is None:
              rel_uri = builder.get_relative_uri(
                  docname, refnode["refuri"]
              )
              refnode["refuri"] = rel_uri + refnode["anchorname"]
      return newnode
  
imports: from __future__ import annotations
  from typing import TYPE_CHECKING, Any, TypeVar
  from docutils import nodes
  from docutils.nodes import Element, Node
  from sphinx import addnodes
  from sphinx.locale import __
  from sphinx.util import logging, url_re
  from sphinx.util.matching import Matcher
  from sphinx.util.nodes import _only_node_keep_children, clean_astext
label_desc: Use image node_id 4 for calling a global function with example usage: _resolve_toctree(env, docname, builder, toctree) and returns: newnode, None, None, None