Preliminary refactoring, more snapshots

.vscode/settings.json

@@ -16,4 +16,5 @@
     "python.testing.cwd": "${workspaceFolder}/doc",
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true,
+    "python.analysis.extraPaths": ["${workspaceFolder}/doc/src", "${workspaceFolder}/doc/test"]
 }

doc/pyproject.toml

@@ -7,7 +7,7 @@ markers = [
     "file_contents: data for fixtures to write to files",
     "fixture_data: other misc data",
 ]
-pythonpath = ["."]
+pythonpath = ["src", "test"]
 
 [tool.coverage.report]
 include_namespace_packages = true

doc/requirements.txt

@@ -1,3 +1,4 @@
 black==22.10.0               # formatting
 pytest==7.3.1                # testing framework
 syrupy==4.0.2                # snapshot tests
+typed-argument-parser==1.8.0 # better argument parsing

doc/src/collate_data.py

@@ -4,7 +4,7 @@ import os  # listdir
 import re  # parsing
 from collections import namedtuple
 from html import escape
-from sys import argv, stdout
+from typing import TextIO
 
 # TO USE: put in Hexcasting root dir, collate_data.py src/main/resources hexcasting thehexbook out.html
 
@@ -725,32 +725,17 @@ def write_book(out, book):
                 write_category(out, book, category)
 
 
-def main(argv):
+def write_docs(book, template_f: TextIO, output_f: TextIO):
-    if len(argv) < 5:
+    for line in template_f:
-        print(
-            f"Usage: {argv[0]} <resources dir> <mod name> <book name> <template file> [<output>]"
-        )
-        return
-    root = argv[1]
-    mod_name = argv[2]
-    book_name = argv[3]
-    book = parse_book(root, mod_name, book_name)
-    template_file = argv[4]
-    with open(template_file, "r", encoding="utf-8") as fh:
-        with stdout if len(argv) < 6 else open(argv[5], "w", encoding="utf-8") as out:
-            for line in fh:
         if line.startswith("#DO_NOT_RENDER"):
             _, *blacklist = line.split()
             book["blacklist"].update(blacklist)
+
         if line.startswith("#SPOILER"):
             _, *spoilers = line.split()
             book["spoilers"].update(spoilers)
         elif line == "#DUMP_BODY_HERE\n":
-                    write_book(Stream(out), book)
+            write_book(Stream(output_f), book)
-                    print("", file=out)
+            print("", file=output_f)
         else:
-                    print(line, end="", file=out)
+            print(line, end="", file=output_f)
-
-
-if __name__ == "__main__":
-    main(argv)

doc/src/main.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+from sys import stdout
+
+from collate_data import parse_book, write_docs
+from tap import Tap
+
+
+# CLI arguments
+class Args(Tap):
+    """example: main.py ../Common/src/main/resources hexcasting thehexbook template.html out.html"""
+
+    resources_dir: Path
+    mod_name: str
+    book_name: str
+    template_file: Path
+    output_file: Path | None
+
+    @property
+    def root(self) -> Path:
+        return self.resources_dir
+
+    def configure(self):
+        # set all arguments as positional
+        self.add_argument("resources_dir")
+        self.add_argument("mod_name")
+        self.add_argument("book_name")
+        self.add_argument("template_file")
+        self.add_argument("output_file", nargs="?")
+
+
+def main(args: Args) -> None:
+    book = parse_book(args.root.as_posix(), args.mod_name, args.book_name)
+
+    with args.template_file.open("r", encoding="utf-8") as template_f:
+        if args.output_file:
+            with args.output_file.open("w", encoding="utf-8") as output_f:
+                write_docs(book, template_f, output_f)
+        else:
+            write_docs(book, template_f, stdout)
+
+
+# entry point - just read the CLI args and run our main function with them
+if __name__ == "__main__":
+    main(Args().parse_args())

doc/test/test_snapshot.py

@@ -1,25 +1,52 @@
+import subprocess
+import sys
+from dataclasses import dataclass
 from pathlib import Path
 
-from collate_data import main
+import pytest
+from main import Args, main
 from syrupy.assertion import SnapshotAssertion
 
 
-def test_full_html(snapshot: SnapshotAssertion, tmp_path: Path):
+@dataclass
-    # generate output docs html file and assert it hasn't changed vs. the snapshot
+class DocgenArgs:
-    # arrange
+    out_path: Path
+    snapshot: SnapshotAssertion
+    argv: list[str]
+
+    def assert_out_path(self):
+        actual = self.out_path.read_text()
+        assert actual == self.snapshot
+
+
+@pytest.fixture
+def docgen(tmp_path: Path, snapshot: SnapshotAssertion) -> DocgenArgs:
+    # arguments we want to pass to the docgen
     out_path = tmp_path / "out.html"
-    argv = [
+    return DocgenArgs(
-        "collate_data.py",
+        out_path,
-        "../Common/src/main/resources",  # resources dir
+        snapshot,
-        "hexcasting",  # mod name
+        [
-        "thehexbook",  # book name
+            "../Common/src/main/resources",
-        "template.html",  # template file
+            "hexcasting",
-        out_path.as_posix(),  # output file
+            "thehexbook",
-    ]
+            "template.html",
+            out_path.as_posix(),
+        ],
+    )
 
-    # act
-    main(argv)
 
-    # assert
+def test_file(docgen: DocgenArgs):
-    actual = out_path.read_text()
+    # generate output docs html file and assert it hasn't changed vs. the snapshot
-    assert actual == snapshot
+    main(Args().parse_args(docgen.argv))
+    docgen.assert_out_path()
+
+
+def test_cmd(docgen: DocgenArgs):
+    # as above, but running the command we actually want to be using
+    subprocess.run(
+        [sys.executable, "src/main.py"] + docgen.argv,
+        stdout=sys.stdout,
+        stderr=sys.stderr,
+    )
+    docgen.assert_out_path()