clang-tools-extra/docs/clang-tidy/checks/gen-static-analyzer-docs.py

"""
Generates documentation based off the available static analyzers checks
References Checkers.td to determine what checks exist
"""

import argparse
import subprocess
import json
import os
import re

"""Get path of script so files are always in correct directory"""
__location__ = os.path.realpath(os.path.join(os.getcwd(), os.path.dirname(__file__)))

"""Get dict of checker related info and parse for full check names

Returns:
  checkers: dict of checker info
"""


def get_checkers(checkers_td_directory):
    p = subprocess.Popen(
        [
            "llvm-tblgen",
            "--dump-json",
            "-I",
            checkers_td_directory,
            checkers_td_directory + "Checkers.td",
        ],
        stdout=subprocess.PIPE,
    )
    table_entries = json.loads(p.communicate()[0])
    documentable_checkers = []
    checkers = table_entries["!instanceof"]["Checker"]
    packages = table_entries["!instanceof"]["Package"]

    for checker_ in checkers:
        checker = table_entries[checker_]
        checker_name = checker["CheckerName"]
        package_ = checker["ParentPackage"]["def"]
        package = table_entries[package_]
        package_name = package["PackageName"]
        checker_package_prefix = package_name
        parent_package_ = package["ParentPackage"]
        hidden = (checker["Hidden"] != 0) or (package["Hidden"] != 0)

        while parent_package_ != None:
            parent_package = table_entries[parent_package_["def"]]
            checker_package_prefix = (
                parent_package["PackageName"] + "." + checker_package_prefix
            )
            hidden = hidden or parent_package["Hidden"] != 0
            parent_package_ = parent_package["ParentPackage"]

        full_package_name = (
            "clang-analyzer-" + checker_package_prefix + "." + checker_name
        )
        anchor_url = re.sub(
            "\.", "-", checker_package_prefix + "." + checker_name
        ).lower()

        if not hidden and "alpha" not in full_package_name.lower():
            checker["FullPackageName"] = full_package_name
            checker["AnchorUrl"] = anchor_url
            documentable_checkers.append(checker)

    documentable_checkers.sort(key=lambda x: x["FullPackageName"])
    return documentable_checkers


"""Generate documentation for checker

Args:
  checker: Checker for which to generate documentation.
  only_help_text: Generate documentation based off the checker description.
    Used when there is no other documentation to link to.
"""


def generate_documentation(checker, only_help_text=False):
    with open(
        os.path.join(__location__, checker["FullPackageName"] + ".rst"), "w"
    ) as f:
        f.write(".. title:: clang-tidy - %s\n" % checker["FullPackageName"])
        if not only_help_text:
            f.write(".. meta::\n")
            f.write(
                "   :http-equiv=refresh: 5;URL=https://clang.llvm.org/docs/analyzer/checkers.html#%s\n"
                % checker["AnchorUrl"]
            )
        f.write("\n")
        f.write("%s\n" % checker["FullPackageName"])
        f.write("=" * len(checker["FullPackageName"]) + "\n")
        f.write("\n")
        if only_help_text:
            f.write("%s\n" % checker["HelpText"])
        else:
            f.write(
                "The %s check is an alias, please see\n" % checker["FullPackageName"]
            )
            f.write(
                "`Clang Static Analyzer Available Checkers <https://clang.llvm.org/docs/analyzer/checkers.html#%s>`_\n"
                % checker["AnchorUrl"]
            )
            f.write("for more information.\n")
        f.close()


"""Update list.rst to include the new checks

Args:
  checkers: dict acquired from get_checkers()
"""


def update_documentation_list(checkers):
    with open(os.path.join(__location__, "list.rst"), "r+") as f:
        f_text = f.read()
        header, check_text = f_text.split(".. toctree::\n")
        checks = check_text.split("\n")
        for checker in checkers:
            if ("   %s" % checker["FullPackageName"]) not in checks:
                checks.append("   %s" % checker["FullPackageName"])
        checks.sort()

        # Overwrite file with new data
        f.seek(0)
        f.write(header)
        f.write(".. toctree::")
        for check in checks:
            f.write("%s\n" % check)
        f.close()


default_path_monorepo = "../../../../clang/include/clang/StaticAnalyzer/Checkers/"
default_path_in_tree = "../../../../../include/clang/StaticAnalyzer/Checkers/"


def parse_arguments():
    """Set up and parse command-line arguments
    Returns:
      file_path: Path to Checkers.td"""
    usage = """Parse Checkers.td to generate documentation for static analyzer checks"""
    parse = argparse.ArgumentParser(description=usage)

    file_path_help = """Path to Checkers directory
                    defaults to ../../../../clang/include/clang/StaticAnalyzer/Checkers/ if it exists
                    then to ../../../../../include/clang/StaticAnalyzer/Checkers/"""

    default_path = None
    if os.path.exists(default_path_monorepo):
        default_path = default_path_monorepo
    elif os.path.exists(default_path_in_tree):
        default_path = default_path_in_tree

    parse.add_argument(
        "file", type=str, help=file_path_help, nargs="?", default=default_path
    )
    args = parse.parse_args()

    if args.file is None:
        print("Could not find Checkers directory. Please see -h")
        exit(1)

    return args.file


def main():
    file_path = parse_arguments()
    checkers = get_checkers(file_path)
    for checker in checkers:
        # No documentation nor alpha documentation
        if checker["Documentation"][1] == 0 and checker["Documentation"][0] == 0:
            generate_documentation(checker, True)
        else:
            generate_documentation(checker)
        print("Generated documentation for: %s" % checker["FullPackageName"])
    update_documentation_list(checkers)


if __name__ == "__main__":
    main()