parameters: (*, out_dir, temp_dir, modules, quick)
return_statement: return ["", "classes.html", "modules.html"]
docstring: Generates into out_dir; writes scratch files into temp_dir.
      As a precondition, both directories must already exist and be empty.
docstring_summary: Generates into out_dir; writes scratch files into temp_dir.
      As a precondition, both directories must already exist and be empty.
docstring_tokens: Generates into out_dir ; writes scratch files into temp_dir . As a precondition both directories must already exist and be empty .
function: def _build(*, out_dir, temp_dir, modules, quick):
      """Generates into out_dir; writes scratch files into temp_dir.
      As a precondition, both directories must already exist and be empty.
      """
      manifest = runfiles.Create()
  
      # Find drake's sources.
      drake_workspace = os.path.dirname(os.path.realpath(
          manifest.Rlocation("drake/.bazelproject")))
      assert os.path.exists(drake_workspace), drake_workspace
      assert os.path.exists(join(drake_workspace, "WORKSPACE")), drake_workspace
  
      # Find doxygen.
      doxygen = manifest.Rlocation("doxygen/doxygen")
      assert os.path.exists(doxygen), doxygen
  
      # Find dot.
      dot = "/usr/bin/dot"
      assert os.path.exists(dot), dot
  
      # Configure doxygen.
      doxyfile = _generate_doxyfile(
          manifest=manifest,
          out_dir=out_dir,
          temp_dir=temp_dir,
          dot=(dot if not quick else ""))
  
      # Prepare our input.
      symlink_input(
          "drake/doc/doxygen_cxx/doxygen_input.txt", temp_dir)
      _generate_doxygen_header(
          doxygen=doxygen,
          temp_dir=temp_dir,
      )
      _symlink_headers(
          drake_workspace=drake_workspace,
          temp_dir=temp_dir,
          modules=modules)
  
      # Run doxygen.
      check_call([doxygen, doxyfile], cwd=temp_dir)
  
      # Post-process its log, and check for errors. If we are building only a
      # subset of the docs, we are likely to encounter errors due to the missing
      # sections, so we'll only enable the promotion of warnings to errors when
      # we're building all of the C++ documentation.
      check_for_errors = (len(modules) == 0)
      with open(f"{temp_dir}/doxygen.log", encoding="utf-8") as f:
          lines = [
              line.strip().replace(f"{temp_dir}/", "")
              for line in f.readlines()
          ]
      _postprocess_doxygen_log(lines, check_for_errors)
  
      # Collect the list of all HTML output files.
      html_files = []
      for dirpath, _, filenames in os.walk(out_dir):
          for filename in filenames:
              if filename.endswith(".html"):
                  html_files.append(relpath(join(dirpath, filename), out_dir))
  
      # Fix the formatting of deprecation text (see drake#15619 for an example).
      perl_statements = [
          # Remove quotes around the removal date.
          r's#(removed from Drake on or after) "(....-..-..)" *\.#\1 \2.#;',
          # Remove all quotes within the explanation text, i.e., the initial and
          # final quotes, as well as internal quotes that might be due to C++
          # multi-line string literals.
          # - The quotes must appear after a "_deprecatedNNNNNN" anchor.
          # - The quotes must appear before a "<br />" end-of-line.
          # Example lines:
          # <dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000013">Deprecated:</a></b></dt><dd>"Use RotationMatrix::MakeFromOneVector()." <br />  # noqa
          # <dd><a class="anchor" id="_deprecated000013"></a>"Use RotationMatrix::MakeFromOneVector()." <br />  # noqa
          r'while (s#(?<=_deprecated\d{6}")([^"]*)"(.*?<br)#\1\2#) {};',
      ]
      while html_files:
          # Work in batches of 100, so we don't overflow the argv limit.
          first, html_files = html_files[:100], html_files[100:]
          check_call(["perl", "-pi", "-e", "".join(perl_statements)] + first,
                     cwd=out_dir)
  
      # The nominal pages to offer for preview.
      return ["", "classes.html", "modules.html"]
function_tokens: def _build ( * , out_dir , temp_dir , modules , quick ) : manifest = runfiles . Create ( ) # Find drake's sources. drake_workspace = os . path . dirname ( os . path . realpath ( manifest . Rlocation ( "drake/.bazelproject" ) ) ) assert os . path . exists ( drake_workspace ) , drake_workspace assert os . path . exists ( join ( drake_workspace , "WORKSPACE" ) ) , drake_workspace # Find doxygen. doxygen = manifest . Rlocation ( "doxygen/doxygen" ) assert os . path . exists ( doxygen ) , doxygen # Find dot. dot = "/usr/bin/dot" assert os . path . exists ( dot ) , dot # Configure doxygen. doxyfile = _generate_doxyfile ( manifest = manifest , out_dir = out_dir , temp_dir = temp_dir , dot = ( dot if not quick else "" ) ) # Prepare our input. symlink_input ( "drake/doc/doxygen_cxx/doxygen_input.txt" , temp_dir ) _generate_doxygen_header ( doxygen = doxygen , temp_dir = temp_dir , ) _symlink_headers ( drake_workspace = drake_workspace , temp_dir = temp_dir , modules = modules ) # Run doxygen. check_call ( [ doxygen , doxyfile ] , cwd = temp_dir ) # Post-process its log, and check for errors. If we are building only a # subset of the docs, we are likely to encounter errors due to the missing # sections, so we'll only enable the promotion of warnings to errors when # we're building all of the C++ documentation. check_for_errors = ( len ( modules ) == 0 ) with open ( f"{temp_dir}/doxygen.log" , encoding = "utf-8" ) as f : lines = [ line . strip ( ) . replace ( f"{temp_dir}/" , "" ) for line in f . readlines ( ) ] _postprocess_doxygen_log ( lines , check_for_errors ) # Collect the list of all HTML output files. html_files = [ ] for dirpath , _ , filenames in os . walk ( out_dir ) : for filename in filenames : if filename . endswith ( ".html" ) : html_files . append ( relpath ( join ( dirpath , filename ) , out_dir ) ) # Fix the formatting of deprecation text (see drake#15619 for an example). perl_statements = [ # Remove quotes around the removal date. r's#(removed from Drake on or after) "(....-..-..)" *\.#\1 \2.#;' , # Remove all quotes within the explanation text, i.e., the initial and # final quotes, as well as internal quotes that might be due to C++ # multi-line string literals. # - The quotes must appear after a "_deprecatedNNNNNN" anchor. # - The quotes must appear before a "<br />" end-of-line. # Example lines: # <dl class="deprecated"><dt><b><a class="el" href="deprecated.html#_deprecated000013">Deprecated:</a></b></dt><dd>"Use RotationMatrix::MakeFromOneVector()." <br />  # noqa # <dd><a class="anchor" id="_deprecated000013"></a>"Use RotationMatrix::MakeFromOneVector()." <br />  # noqa r'while (s#(?<=_deprecated\d{6}")([^"]*)"(.*?<br)#\1\2#) {};' , ] while html_files : # Work in batches of 100, so we don't overflow the argv limit. first , html_files = html_files [ : 100 ] , html_files [ 100 : ] check_call ( [ "perl" , "-pi" , "-e" , "" . join ( perl_statements ) ] + first , cwd = out_dir ) # The nominal pages to offer for preview. return [ "" , "classes.html" , "modules.html" ]