class_docstr: Builds target formats from the reST sources.
class_docstr_tok: ["Builds","target","formats","from","the","reST","sources","."]
docstr: Main build method.
  
  First updates the environment, and then calls
  :meth:`!write`.
code: def build(
      self,
      docnames: Iterable[str] | None,
      summary: str | None = None,
      method: str = "update",
  ) -> None:
      """Main build method.
  
      First updates the environment, and then calls
      :meth:`!write`.
      """
      if summary:
          logger.info(bold(__("building [%s]: ") % self.name) + summary)
  
      # while reading, collect all warnings from docutils
      with logging.pending_warnings():
          updated_docnames = set(self.read())
  
      doccount = len(updated_docnames)
      logger.info(
          bold(__("looking for now-outdated files... ")), nonl=True
      )
      for docname in self.env.check_dependents(
          self.app, updated_docnames
      ):
          updated_docnames.add(docname)
      outdated = len(updated_docnames) - doccount
      if outdated:
          logger.info(__("%d found"), outdated)
      else:
          logger.info(__("none found"))
  
      if updated_docnames:
          # save the environment
          from sphinx.application import ENV_PICKLE_FILENAME
  
          with progress_message(__("pickling environment")), open(
              path.join(self.doctreedir, ENV_PICKLE_FILENAME), "wb"
          ) as f:
              pickle.dump(self.env, f, pickle.HIGHEST_PROTOCOL)
  
          # global actions
          self.app.phase = BuildPhase.CONSISTENCY_CHECK
          with progress_message(__("checking consistency")):
              self.env.check_consistency()
      else:
          if method == "update" and not docnames:
              logger.info(bold(__("no targets are out of date.")))
              return
  
      self.app.phase = BuildPhase.RESOLVING
  
      # filter "docnames" (list of outdated files) by the updated
      # found_docs of the environment; this will remove docs that
      # have since been removed
      if docnames and docnames != ["__all__"]:
          docnames = set(docnames) & self.env.found_docs
  
      # determine if we can write in parallel
      if (
          parallel_available
          and self.app.parallel > 1
          and self.allow_parallel
      ):
          self.parallel_ok = self.app.is_parallel_allowed("write")
      else:
          self.parallel_ok = False
  
      #  create a task executor to use for misc. "finish-up" tasks
      # if self.parallel_ok:
      #     self.finish_tasks = ParallelTasks(self.app.parallel)
      # else:
      # for now, just execute them serially
      self.finish_tasks = SerialTasks()
  
      # write all "normal" documents (or everything for some builders)
      self.write(docnames, list(updated_docnames), method)
  
      # finish (write static files etc.)
      self.finish()
  
      # wait for all tasks
      self.finish_tasks.join()
  
imports: from __future__ import annotations
  import codecs
  import pickle
  import time
  from os import path
  from typing import TYPE_CHECKING, Any
  from docutils import nodes
  from docutils.utils import DependencyList
  from sphinx.environment import CONFIG_CHANGED_REASON, CONFIG_OK, BuildEnvironment
  from sphinx.environment.adapters.asset import ImageAdapter
  from sphinx.errors import SphinxError
  from sphinx.locale import __
  from sphinx.util import UnicodeDecodeErrorHandler, get_filetype, import_object, logging, rst
  from sphinx.util.build_phase import BuildPhase
  from sphinx.util.console import bold
  from sphinx.util.display import progress_message, status_iterator
  from sphinx.util.docutils import sphinx_domains
  from sphinx.util.i18n import CatalogInfo, CatalogRepository, docname_to_domain
  from sphinx.util.osutil import SEP, ensuredir, relative_uri, relpath
  from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, parallel_available
  from sphinx import directives
  from sphinx import roles
label_desc: Use image node_id 18 for calling the Builder obj's underlying member method code with example usage: obj.build(docnames, summary, method) without return types