docs: def link_files(files: set, workspace_src_dir: str,
                 common_parent: str, conf):
      """Sync the list of files and directories in `files` to destination
         directory specified by `workspace_src_dir`.
  
      "Sync" in the sense that every file given in `files` will be
      hard-linked under `workspace_src_dir` after this function returns, and no
      other files will exist under `workspace_src_dir`.
  
      For directories in `files`, hard-links of contained files are
      created recursively.
  
      All paths in `files`, and the `workspace_src_dir`, must be relative
      to `conf.project_root`.
  
      If `common_parent` is given, and it is a common parent directory of all
      `files`, then the `commonm_parent` part is truncated from the
      sync'ed files destination path under `workspace_src_dir`.
  
      :raises FileNotFoundError: If `files` contains files or directories
                                 that do not exist.
  
      :raises ValueError: If `common_parent` is given (not `None`), but is *NOT*
                          a common parent of all `files`.
      """
      norm_dir = normpath(workspace_src_dir)
      base_dir = ''
      if common_parent:
          common_parent = normpath(common_parent)
          base_dir = commonpath(list(files) + [common_parent])
          if base_dir != common_parent:
              raise ValueError('{} is not the common parent of all target '
                               'sources and data'.format(common_parent))
          logger.debug(
              'Rebasing files in image relative to common parent dir {}',
              base_dir)
      num_linked = 0
      for src in files:
          abs_src = join(conf.project_root, src)
          abs_dest = join(conf.project_root, workspace_src_dir,
                          relpath(src, base_dir))
          link_node(abs_src, abs_dest, conf.builders_workspace_dir in src)
          num_linked += 1
      return num_linked