tools/devshell/contrib/lib/rust/rustdoc_link_actions.py

#!/usr/bin/env fuchsia-vendored-python
# Copyright 2024 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.

"""These dataclasses model the set of actions needed to build and link Rust
documentation.

Instances of `Action` are generated by rustdoc-link.py when it's provided with
`--dry-run`.

These actions are currently executed by
* rustdoc-link.py itself, and
* the infra recipes that build our rustdoc index.

When they are shared with the infra recipes, these actions are exported as
JSON, e.g. json.dumps(dataclasses.asdict(action)), with paths relative to the
$FUCHSIA_BUILD_DIR.

The external recipes should only have to implement high-level glue code that
calls the equivalent of shell commands, as is best practice. The logic for
deciding what to build, document, and copy should live in rustdoc link or other
code in this repository.

These dataclasses are declared outside rustdoc-link.py so that we can abstract
the code that generates the documentation plan from the code that executes it.
The authors of the infra recipes can refer to this schema and the documented
behavior when implementing the recipes.

Changes to this schema must be reflected in the infra repo.
"""

from dataclasses import dataclass

BuildLabel = str
"""Represents anything that we can give fx build.
"""

ActionPath = str
"""A filesystem path relative to the $FUCHSIA_BUILD_DIR.

Needed because json.dumps does not accept pathlib.Path.
"""


@dataclass
class BuildAction:
    """Execute this by running `fx build {...labels}`"""

    labels: list[BuildLabel]


@dataclass
class RustdocAction:
    """Execute this by calling `rustdoc @{argfile}`

    See <https://doc.rust-lang.org/rustc/command-line-arguments.html#path-load-command-line-flags-from-a-path>.
    """

    argfile: ActionPath


@dataclass
class CopyAction:
    """Execute this by running `cp {...srcs} dst`,

    The directories in `srcs` often have a trailing slash dot `/.`, meaning the
    *contents* of the source directories must be copied instead of the source
    directories themselves. The `cp` command understands this.
    """

    srcs: list[ActionPath]
    dst: ActionPath


@dataclass
class TargetAction:
    """Execute the build_action (if any), the rustdoc_action, and the copy_action,
    in sequence.
    """

    build_action: BuildAction | None
    rustdoc_action: RustdocAction
    copy_action: CopyAction


@dataclass
class ZipAction:
    """To execute this, run `cd {zip_from} && zip {zip_to} .`"""

    zip_from: ActionPath
    zip_to: ActionPath


@dataclass
class VerifyAction:
    """To execute this, run `{executable} {...args}`.

    If this verification action exits unsuccessfully, then the docs should be
    presumed to be broken.

    Make sure to run this script with FUCHSIA_BUILD_DIR and FUCHSIA_DIR set.
    Run it with the FUCHSIA_BUILD_DIR as the current working directory.
    """

    executable: ActionPath
    args: list[str]


@dataclass
class Action:
    """Execute the host_action, the fuchsia_action, and the zip_action (if any), in
    sequence.
    """

    host_action: TargetAction
    fuchsia_action: TargetAction
    zip_action: ZipAction | None
    verify_action: VerifyAction