docs.make

  1#!/usr/bin/env python3
  2"""
  3pdoc is used to generate documentation, outputting files into the `docs` folder.
  4All the configuration files are in the `/docs/config` folder.
  5
  6(c) 2020-2024 TurnAround Factor, Inc.
  7
  8CUI DISTRIBUTION CONTROL
  9Controlled by: DLA J68 R&D SBIP
 10CUI Category: Small Business Research and Technology
 11Distribution/Dissemination Controls: PROTECTED BY SBIR DATA RIGHTS
 12POC: GOV SBIP Program Manager Denise Price, 571-767-0111
 13Distribution authorized to U.S. Government Agencies only, to protect information not owned by the
 14U.S. Government and protected by a contractor’s ‘limited rights’ statement, or received with the understanding that
 15it is not routinely transmitted outside the U.S. Government (determination made September 14, 2024). Other requests
 16for this document shall be referred to ACOR DLA Logistics Operations (J-68), 8725 John J. Kingman Rd., Suite 4317,
 17Fort Belvoir, VA 22060-6221
 18
 19SBIR DATA RIGHTS
 20Contract No.:SP4701-23-C-0083
 21Contractor Name: TurnAround Factor, Inc.
 22Contractor Address: 10365 Wood Park Ct. Suite 313 / Ashland, VA 23005
 23Expiration of SBIR Data Rights Period: September 24, 2029
 24The Government's rights to use, modify, reproduce, release, perform, display, or disclose technical data or computer
 25software marked with this legend are restricted during the period shown as provided in paragraph (b)(4) of the Rights
 26in Noncommercial Technical Data and Computer Software--Small Business Innovative Research (SBIR) Program clause
 27contained in the above identified contract. No restrictions apply after the expiration date shown above. Any
 28reproduction of technical data, computer software, or portions thereof marked with this legend must also reproduce
 29the markings.
 30"""
 31import argparse
 32import os
 33import re
 34from pathlib import Path
 35
 36import pdoc
 37import pytest
 38
 39import hitl_tester
 40from hitl_tester.__main__ import test_plans, read_test_plan
 41from hitl_tester.modules.bms_types import TestFlags
 42
 43pytest.flags = TestFlags(True, True)
 44
 45_ROOT_DIRECTORY = Path(__file__).parent.parent
 46
 47
 48def main() -> None:
 49    """Generate documentation."""
 50    # Make sure we're in the root directory of the project
 51    os.chdir(_ROOT_DIRECTORY)
 52
 53    # Configure
 54    pdoc.render.configure(
 55        favicon="favicon.ico",
 56        logo_link="https://github.com/turnaroundfactor/HITL",
 57        footer_text=f"TurnAround Factor (pdoc {pdoc.__version__})",
 58        math=True,
 59        mermaid=True,
 60        template_directory=_ROOT_DIRECTORY / "docs" / "config",
 61    )
 62
 63    # Map all test cases to their test plans
 64    test_case_plans: dict[str, list[Path]] = {}  # case : plans
 65    for test_plan in test_plans():
 66        for _, path, _ in read_test_plan(test_plan, argparse.Namespace()):
 67            test_case_plans[path.stem] = test_case_plans.get(path.stem, []) + [
 68                test_plan.relative_to(test_plan.parent.parent)
 69            ]
 70
 71    def generate_extra_description(module_name: str, module_variables: list[pdoc.doc.Variable]) -> str:
 72        """Append test plans and example commands to the test case description."""
 73        lines = []
 74        if parent_test_plans := test_case_plans.get(module_name):
 75            # List test plans
 76            lines.append("Used in these test plans:")
 77            lines.append(chr(10).join(f"- **{test_plan.stem}** ⠀⠀⠀({test_plan})" for test_plan in parent_test_plans))
 78
 79            # List an example command
 80            lines.append("Example Command (warning: test plan may run other test cases):")
 81            hitl_filename = f"./{hitl_tester.__name__}.py"
 82            test_plan = parent_test_plans[0].stem
 83            empty_string = '""'
 84            define_strings = [
 85                f"-D{var.name}={var.default_value if var.default_value != '' else empty_string}"
 86                for var in module_variables
 87                if var.name.isupper() and not var.name.startswith("_")
 88            ]
 89            lines.append(f" - `{hitl_filename} {test_plan} {' '.join(define_strings)}`")
 90
 91        newline = "\n\n"
 92        return f"{newline}{newline.join(lines)}"
 93
 94    pdoc.render.env.globals["test_plans"] = generate_extra_description
 95
 96    # Auto-convert GitHub style issue or PR links
 97    pdoc.render_helpers.markdown_link_patterns.append(
 98        (
 99            re.compile(  # Pattern is owner/repo#issue
100                r"""
101        ([\w-]+)  # Owner
102        /         # Forward slash
103        ([\w-]+)  # Repository
104        \#        # Pound sign
105        (\d+)     # Issue number
106        """,
107                re.VERBOSE,
108            ),
109            r"https://github.com/\1/\2/issues/\3/",
110        )
111    )
112
113    # Generate
114    pdoc.pdoc(
115        _ROOT_DIRECTORY / "docs",
116        "hitl_tester",
117        "!hitl_tester.test_plans",
118        output_directory=_ROOT_DIRECTORY / "docs",
119    )
120
121
122if __name__ == "__main__":
123    main()