ci: ensure ansible-core files exist before running docs build (#1756) (#1783)

Also, make KEEP_DIRS and KEEP_FILES constants to make the main function
cleaner.

Fixes: #1056
(cherry picked from commit 0d35022)

Co-authored-by: Maxwell G <[email protected]>

Author: oraNod

docs/bin/clone-core.py

@@ -18,11 +18,27 @@
 DEFAULT_BRANCH = (ROOT / "docs" / "ansible-core-branch.txt").read_text().strip()
 DEFAULT_ANSIBLE_CORE_REPO = "https://github.com/ansible/ansible"
 
+KEEP_DIRS = (
+    "bin",
+    "lib",
+    "packaging",
+    "test/lib",
+)
+
+KEEP_FILES = (
+    "MANIFEST.in",
+    "pyproject.toml",
+    "requirements.txt",
+    "setup.cfg",
+    "setup.py",
+)
+
 
 @dataclasses.dataclass()
 class Args:
     branch: str | None
     repo: str
+    check: bool
 
 
 def parse_args(args: list[str] | None = None) -> Args:
@@ -47,24 +63,25 @@ def parse_args(args: list[str] | None = None) -> Args:
         help="ansible-core repository to check out. Default: %(default)s",
         default=DEFAULT_ANSIBLE_CORE_REPO,
     )
+    parser.add_argument(
+        "--check",
+        action=argparse.BooleanOptionalAction,
+        help="Ensure that the necessary files exist."
+        " If they don't clone new ones from ansible-core."
+        " Otherwise, leave the existing versions alone.",
+    )
     return Args(**vars(parser.parse_args(args)))
 
 
 def main(args: Args) -> None:
-    keep_dirs = [
-        "bin",
-        "lib",
-        "packaging",
-        "test/lib",
-    ]
-
-    keep_files = [
-        "MANIFEST.in",
-        "pyproject.toml",
-        "requirements.txt",
-        "setup.cfg",
-        "setup.py",
-    ]
+    if (
+        args.check
+        and all(pathlib.Path(file).is_file() for file in KEEP_FILES)
+        and all(pathlib.Path(directory).is_dir() for directory in KEEP_DIRS)
+    ):
+        print("The necessary core files already exist.")
+        print("Run 'nox -e clone-core' without --check to update the core files.")
+        return
 
     with tempfile.TemporaryDirectory() as temp_dir:
         cmd: list[str] = ["git", "clone", args.repo, "--depth=1"]
@@ -73,7 +90,7 @@ def main(args: Args) -> None:
         cmd.append(temp_dir)
         subprocess.run(cmd, check=True)
 
-        for keep_dir in keep_dirs:
+        for keep_dir in KEEP_DIRS:
             src = pathlib.Path(temp_dir, keep_dir)
             dst = pathlib.Path.cwd() / keep_dir
 
@@ -86,7 +103,7 @@ def main(args: Args) -> None:
 
             (dst / ".gitignore").write_text("*")
 
-        for keep_file in keep_files:
+        for keep_file in KEEP_FILES:
             src = pathlib.Path(temp_dir, keep_file)
             dst = pathlib.Path.cwd() / keep_file
 

noxfile.py

@@ -124,6 +124,13 @@ def clone_core(session: nox.Session):
 ]
 
 
+def _clone_core_check(session: nox.Session) -> None:
+    """
+    Helper function to run the clone-core script with "--check"
+    """
+    session.run("python", "docs/bin/clone-core.py", "--check")
+
+
 def _relaxed_parser(session: nox.Session) -> ArgumentParser:
     """
     Generate an argument parser with a --relaxed option.
@@ -158,6 +165,7 @@ def checkers(session: nox.Session, test: str):
     args = _relaxed_parser(session).parse_args(session.posargs)
 
     install(session, req="requirements-relaxed" if args.relaxed else "requirements")
+    _clone_core_check(session)
     session.run("make", "-C", "docs/docsite", "clean", external=True)
     session.run("python", "tests/checkers.py", test)
 
@@ -174,6 +182,7 @@ def make(session: nox.Session):
     args = parser.parse_args(session.posargs)
 
     install(session, req="requirements-relaxed" if args.relaxed else "requirements")
+    _clone_core_check(session)
     make_args: list[str] = [
         f"PYTHON={_env_python(session)}",
         *(args.make_args or ("clean", "coredocs")),