tools/docsgen/BUILD.gn

# Copyright 2021 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import("//build/compiled_action.gni")
import("//build/config/build_api_module.gni")
import("//build/python/python_binary.gni")
import("//build/sdk/sdk_documentation.gni")

group("docsgen") {
  testonly = true
  deps = [ ":generated_docs" ]
}

# Runs one time python assemblydoc generation script.
compiled_action("invoke_assemblydoc") {
  tool = "//tools/assemblydoc:assemblydoc_bin"
  tool_output_name = "assemblydoc"
  deps = [ "//tools/assemblydoc($host_toolchain)" ]
  args = [
    "--archive-output",
    rebase_path("$target_out_dir/assemblydoc.tar.gz", root_build_dir),
  ]

  metadata = {
    # Record metadata for the //tools/docsgen build API.
    generated_docset = [
      {
        name = "assemblydoc"
        archive = {
          origin_file =
              rebase_path("$target_out_dir/assemblydoc.tar.gz", root_build_dir)
          base_folder = "assemblydoc"
        }
        dest_folder = "sdk/assembly"
      },
    ]
  }
  outputs = [ "$target_out_dir/assemblydoc.tar.gz" ]
}

_fidldoc_transforms_script_target = "fidldoc_transforms"
python_binary(_fidldoc_transforms_script_target) {
  main_source = "//build/fidl/gen_fidldocs.py"
  output_name = "gen_fidldocs.pyz"
  sources = []
  deps = []
}

# Runs one time python fidldoc generation script.
action("invoke_fidldoc") {
  script_output = get_target_outputs(":${_fidldoc_transforms_script_target}")
  script = script_output[0]
  metadata = {
    # Record metadata for the //tools/docsgen build API.
    generated_docset = [
      {
        name = "fidldoc"
        archive = {
          origin_file =
              rebase_path("$target_out_dir/fidldoc.zip", root_build_dir)
          base_folder = "fidldoc"
        }
        dest_folder = "sdk/fidl"
      },
    ]
  }
  inputs = [
    "$root_build_dir/host-tools/fidldoc",
    "$root_build_dir/host-tools/fidldoc.config.json",
    "$root_build_dir/sdk_fidl_json.json",
  ]

  outputs = [ "$target_out_dir/fidldoc.zip" ]
  depfile = "$target_out_dir/$target_name.d"

  args = [
    "--zipped-result",
    "--build-dir",
    rebase_path(root_build_dir, root_build_dir),
    "--out-dir",
    rebase_path(target_out_dir, root_build_dir),
    "--dep-file",
    rebase_path(depfile, root_build_dir),
  ]

  deps = [
    ":${_fidldoc_transforms_script_target}",
    "//build/fidl:sdk_fidl",
    "//tools/fidl/fidldoc:fidldoc_copy_config($host_toolchain)",
    "//tools/fidl/fidldoc($host_toolchain)",
  ]
}

clidoc_tarfile = "clidoc_out.tar.gz"

# Some SDK dependencies lifted from //src/developer/ffx/build/ffx_action.
# This is the actual label for the sdk host tools, and is used to provide the
# path to the sdk molecule manifest.
sdk_host_tools_visibility_bridge_label =
    "//src/developer/ffx/build:internal_sdk_tools_for_ffx($host_toolchain)"

_sdk_host_tools_label = "//sdk:host_tools.internal($host_toolchain)"

sdk_host_tools_manifest =
    get_label_info(_sdk_host_tools_label, "root_out_dir") +
    "/sdk/manifest/host_tools.internal"

compiled_action("invoke_clidoc") {
  tool = "//tools/clidoc:clidoc_bin"
  tool_output_name = "clidoc"
  depfile = "$target_out_dir/$target_name.d"
  deps = [
    "//sdk:host_tools",
    sdk_host_tools_visibility_bridge_label,
  ]
  if (is_host) {
    deps += [
      "//src/developer/ffx/frontends/ffx:ffx_bin_unversioned($host_toolchain)",
      "//src/developer/ffx/tools($host_toolchain)",

      # TODO(https://fxbug.dev/42167576) check if triage belongs in sdk docs.
      "//src/diagnostics/triage:triage_bin",
    ]
  }

  metadata = {
    # Record metadata for the //tools/docsgen build API.
    generated_docset = [
      {
        name = "clidoc"
        archive = {
          origin_file =
              rebase_path("$target_out_dir/$clidoc_tarfile", root_build_dir)
          base_folder = "clidoc"
        }
        dest_folder = "tools/sdk"
      },
    ]
  }

  inputs = [ sdk_host_tools_manifest ]
  outputs = [ "$target_out_dir/$clidoc_tarfile" ]
  args = [
    "-o",
    rebase_path("$target_gen_dir/sdk-docs", root_build_dir),
    "--quiet",
    "--archive-path",
    rebase_path("$target_out_dir/$clidoc_tarfile", root_build_dir),
    "--depfile",
    rebase_path(depfile, root_build_dir),
    "--sdk-root",
    rebase_path(root_build_dir, root_build_dir),
    "--sdk-manifest",
    rebase_path(sdk_host_tools_manifest, root_build_dir),
    "--isolate-dir",
    rebase_path(target_gen_dir, root_build_dir),
  ]
}

_helpdoc_script_target = "helpdoc_generation"
helpdoc_tarfile = "helpdoc_out.tar.gz"
python_binary(_helpdoc_script_target) {
  main_source = "//tools/docsgen/gen_helpdocs.py"
  output_name = "gen_helpdocs.pyz"
  sources = []
  deps = []
}

_docsgen_transforms_script_target = "docsgen_transforms"
python_binary(_docsgen_transforms_script_target) {
  main_source = "//tools/docsgen/docsgen_transforms.py"
  output_name = "docsgen_transforms.pyz"
  sources = []
  deps = []
}

# Runs one time python helpdoc generation script.
action("invoke_helpdoc") {
  # TODO(https://fxbug.dev/42168642): Remove this exception when this action no
  # longer executes fx tools.
  hermetic_deps = false

  script_output = get_target_outputs(":${_helpdoc_script_target}")
  script = script_output[0]
  depfile = "$target_out_dir/$target_name.d"
  metadata = {
    # Record metadata for the //tools/docsgen build API.
    generated_docset = [
      {
        name = "helpdoc"
        archive = {
          origin_file =
              rebase_path("$target_out_dir/$helpdoc_tarfile", root_build_dir)
          base_folder = "helpdoc"
        }
        dest_folder = "tools/fx"
      },
    ]
  }
  outputs = [
    "$target_out_dir/$helpdoc_tarfile",
    "$target_gen_dir/helpdoc.log",
  ]

  args = [
    "--out-path",
    rebase_path("$target_out_dir/$helpdoc_tarfile", root_build_dir),
    "--src-dir",
    rebase_path("//", root_build_dir),
    "--log-to-file",
    rebase_path("$target_gen_dir/helpdoc.log", root_build_dir),
    "--depfile",
    rebase_path(depfile, root_build_dir),
  ]

  deps = [ ":${_helpdoc_script_target}" ]
}

action("create_syscall_docs") {
  script = "gen_syscalls_toc.py"

  deps = [ "//zircon/vdso:syscall_docs.zip" ]
  inputs = [ get_label_info(deps[0], "target_out_dir") + "/syscall_docs.zip" ]
  outputs = [ "${target_out_dir}/syscalls.zip" ]

  args = [
    "--input",
    rebase_path(inputs[0], root_build_dir),
    "--output",
    rebase_path(outputs[0], root_build_dir),
    "--reference-root",
    "/reference/syscalls",
  ]

  metadata = {
    generated_docset = [
      {
        name = "syscalls"
        archive = {
          origin_file = rebase_path(outputs[0], root_build_dir)
        }
        dest_folder = "syscalls"
      },
    ]
  }
}

compiled_action("invoke_cmldoc") {
  tool = "//tools/cmc:cmc"
  tool_output_name = "cmc"
  metadata = {
    # Record metadata for the //tools/docsgen build API.
    generated_docset = [
      {
        name = "cmldoc"
        origin_files = [ rebase_path("$target_out_dir/cmldoc_out/index.md",
                                     root_build_dir) ]
        dest_folder = "sdk/cml"
      },
    ]
  }
  outputs = [ "$target_out_dir/cmldoc_out/index.md" ]
  args = [
    "print-cml-reference",
    "-o",
    rebase_path("$target_out_dir/cmldoc_out/index.md", root_build_dir),
  ]
  deps = [ "//tools/cmc($host_toolchain)" ]
}

# This exposes relevant reference doc paths for infra to upload.
#
# Type: list(scope)
#
#   name:
#     Required: name of the reference docs to be generated. This name
#     will be used to identify the ref doc git commit process downstream
#     in the docsgen recipe.
#     Type: string
#
#   archive:
#     Optional: If this key is present, this denotes that the ref docs
#     are compressed. This is most likely to adhere to hermetic builds.
#     Additional specific parameters will be included pertaining to archive
#     paths.
#     Type: scope
#
#     origin_file:
#        Required: path to compressed archived file holding ref docs.
#        Type: path relative to $root_build_dir
#
#     base_folder:
#        Optional: base folder containing all ref docs once origin file
#        is decompresssed. Alternatively if base folder is not specified.
#        all reference docs are simply decompressed into the current dir.
#        Type: string
#
#   origin_files:
#     Optional: If this key is present, this denotes that the ref docs
#     can be listed and are decompressed.
#     Type: list of file paths relative to $root_build_dir
#
#   dest_folder:
#     Required: path to destination folder within reference docs repo
#     Type: path relative to reference docs repo root directory
#

build_api_module("generated_docs") {
  testonly = true
  data_keys = [ "generated_docset" ]
  deps = [
    ":create_syscall_docs",
    ":invoke_assemblydoc",
    ":invoke_clidoc",
    ":invoke_cmldoc",
    ":invoke_fidldoc",
    ":invoke_helpdoc",
    "//bundles/drivers:create_all_drivers_doc",
    "//sdk/lib/fdio:docs",
  ]
}

# Set up targets and files for sdk_documentation

sdk_docs = [
  {
    target = ":invoke_assemblydoc"
    file = "assemblydoc.tar.gz"
  },
  {
    target = ":invoke_clidoc"
    file = "clidoc_out.tar.gz"
  },
  {
    target = ":invoke_cmldoc"
    file = "cmldoc_out/index.md"
  },
  {
    target = ":invoke_fidldoc"
    file = "fidldoc.zip"
  },
  {
    target = ":invoke_helpdoc"
    file = "helpdoc_out.tar.gz"
  },
  {
    target = "//sdk/lib/fdio:docs"
    file = "fdio.zip"
  },
]

sdk_doc_files = []
sdk_doc_targets = []
foreach(sdk_doc, sdk_docs) {
  src_dir = get_label_info(sdk_doc.target, "target_out_dir")
  sdk_doc_file = sdk_doc.file

  sdk_doc_files += [
    {
      source = "$src_dir/$sdk_doc_file"
      dest = "docs/$sdk_doc_file"
    },
  ]
  sdk_doc_targets += [ sdk_doc.target ]
}

sdk_documentation("ref_docs_sdk") {
  name = "ref_docs"
  category = "partner"

  files = sdk_doc_files
  non_sdk_deps = sdk_doc_targets
}

group("tests") {
  testonly = true
  deps = [ "tests($host_toolchain)" ]
}