tools/devshell/contrib/lib/rust/rustdoc_link_verify.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.

"""Checks generated docs for obvious failures.

We would like to avoid uploading broken documentation.

When this script exits unsuccessfully, do not upload the docs.

This script must strike a balance between ensuring that broken documentation is
not uploaded, and not being too picky. If we depend too much on specific rustdoc
implementation details, we could fail to upload correct docs.

"""

import sys
from argparse import ArgumentParser, RawTextHelpFormatter
from pathlib import Path
from sys import argv, stderr


def generator_empty(gen):
    is_empty = True
    for _ in gen:
        is_empty = False
        break
    return is_empty


def print_failure(*args):
    print(f"{Path(argv[0]).name}:", *args, file=stderr)


def main(doc_root: Path):
    all_okay = True

    def verify(condition, *args):
        if not condition:
            nonlocal all_okay
            all_okay = False
            print_failure(*args)

    # we can assume that our documentation comes with source code at this path, since it's commonly
    # linked to
    verify(
        (doc_root / "src").is_dir(),
        "expected src to be a directory in the docs",
    )
    # the 'host' path component is hardcoded in several places, so it's okay to assert it exists
    verify(
        (doc_root / "host").is_dir(),
        "expected host to be a directory in the docs",
    )
    verify(
        (doc_root / "host" / "src").is_dir(),
        "expected host/src to be a directory in the docs",
    )

    # check for certain types of files in crates with fuchsia targets
    fuchsia_root = doc_root
    verify(
        not generator_empty(fuchsia_root.rglob("index.html")),
        "expected fuchsia-side docs to have at least one index.html file",
    )
    verify(
        not generator_empty(fuchsia_root.rglob("*.css")),
        "expected fuchsia-side docs to have at least one css file",
    )
    verify(
        not generator_empty(fuchsia_root.rglob("*.js")),
        "expected fuchsia-side documentation to have at least one .js file",
    )
    verify(
        not generator_empty((fuchsia_root / "src").glob("*")),
        "expected at least one documented crate for fuchsia",
    )
    # check for certain types of files in crates with host targets
    host_root = doc_root / "host"
    verify(
        not generator_empty(host_root.rglob("index.html")),
        "expected host-side docs to have at least one index.html file",
    )
    verify(
        not generator_empty(host_root.rglob("*.css")),
        "expected host-side docs to have at least one css file",
    )
    verify(
        not generator_empty(host_root.rglob("*.js")),
        "expected host-side documentation to have at least one .js file",
    )
    verify(
        not generator_empty((host_root / "src").glob("*")),
        "expected at least one documented crate for the host",
    )

    if not all_okay:
        print_failure("failed verification")
        sys.exit(1)


def _main_arg_parser() -> ArgumentParser:
    # __doc__ refers to the doc comment at the top of this file. Use the raw formatter
    # so that newlines in the doc comment are newlines in the --help text.
    parser = ArgumentParser(
        description=__doc__,
        formatter_class=RawTextHelpFormatter,
    )
    parser.add_argument(
        "doc_root",
        type=Path,
        help="path to the root of generated documentation",
    )
    parser.set_defaults(func=main)
    return parser


if __name__ == "__main__":
    parser = _main_arg_parser()
    args = parser.parse_args(argv[1:])
    args.func(args.doc_root)