|
| 1 | +import unittest |
| 2 | +import os |
| 3 | +import re |
| 4 | +import glob |
| 5 | +import remodel |
| 6 | +from remodel.operations.valid_operations import valid_operations |
| 7 | + |
| 8 | + |
| 9 | +class TestDocConsistency(unittest.TestCase): |
| 10 | + def setUp(self): |
| 11 | + self.current_dir = os.path.dirname(__file__) |
| 12 | + self.docs_root = os.path.abspath(os.path.join(self.current_dir, "..", "docs", "api")) |
| 13 | + |
| 14 | + def test_operations_are_documented(self): |
| 15 | + """ |
| 16 | + Ensure all operations in valid_operations are listed in docs/api/operations.rst. |
| 17 | + This preserves manual organization while ensuring completeness. |
| 18 | + """ |
| 19 | + docs_path = os.path.join(self.docs_root, "operations.rst") |
| 20 | + |
| 21 | + # Read the documentation file |
| 22 | + with open(docs_path, "r", encoding="utf-8") as f: |
| 23 | + content = f.read() |
| 24 | + |
| 25 | + # Extract all class names documented via autoclass |
| 26 | + # Matches: .. autoclass:: remodel.operations.some_module.ClassName |
| 27 | + documented_classes = set() |
| 28 | + pattern = r"\.\.\s+autoclass::\s+[\w\.]+\.(\w+)" |
| 29 | + |
| 30 | + for match in re.finditer(pattern, content): |
| 31 | + documented_classes.add(match.group(1)) |
| 32 | + |
| 33 | + # Check against the source of truth |
| 34 | + missing_ops = [] |
| 35 | + for op_name, op_class in valid_operations.items(): |
| 36 | + class_name = op_class.__name__ |
| 37 | + if class_name not in documented_classes: |
| 38 | + missing_ops.append(class_name) |
| 39 | + |
| 40 | + # Fail if anything is missing |
| 41 | + if missing_ops: |
| 42 | + self.fail( |
| 43 | + f"\nThe following operations are defined in valid_operations but missing from operations.rst:\n" |
| 44 | + + "\n".join(f"- {op}" for op in missing_ops) |
| 45 | + + "\n\nPlease add them to docs/api/operations.rst under the appropriate section." |
| 46 | + ) |
| 47 | + |
| 48 | + def test_core_is_documented(self): |
| 49 | + """ |
| 50 | + Ensure all classes exported in remodel/__init__.py are documented in docs/api/core.rst. |
| 51 | + """ |
| 52 | + docs_path = os.path.join(self.docs_root, "core.rst") |
| 53 | + |
| 54 | + # Read the documentation file |
| 55 | + with open(docs_path, "r", encoding="utf-8") as f: |
| 56 | + content = f.read() |
| 57 | + |
| 58 | + # Get exported classes from remodel/__init__.py |
| 59 | + # We filter for classes that are actually defined in the package (not modules) |
| 60 | + exported_classes = [ |
| 61 | + name for name in dir(remodel) if not name.startswith("_") and isinstance(getattr(remodel, name), type) |
| 62 | + ] |
| 63 | + |
| 64 | + # Extract documented classes |
| 65 | + documented_classes = set() |
| 66 | + pattern = r"\.\.\s+autoclass::\s+[\w\.]+\.(\w+)" |
| 67 | + |
| 68 | + for match in re.finditer(pattern, content): |
| 69 | + documented_classes.add(match.group(1)) |
| 70 | + |
| 71 | + missing_classes = [] |
| 72 | + for cls_name in exported_classes: |
| 73 | + if cls_name not in documented_classes: |
| 74 | + missing_classes.append(cls_name) |
| 75 | + |
| 76 | + if missing_classes: |
| 77 | + self.fail( |
| 78 | + f"\nThe following core classes are exported by remodel but missing from core.rst:\n" |
| 79 | + + "\n".join(f"- {cls}" for cls in missing_classes) |
| 80 | + + "\n\nPlease add them to docs/api/core.rst." |
| 81 | + ) |
| 82 | + |
| 83 | + def test_cli_is_documented(self): |
| 84 | + """ |
| 85 | + Ensure all CLI scripts in remodel/cli/ are documented in docs/api/cli.rst. |
| 86 | + """ |
| 87 | + docs_path = os.path.join(self.docs_root, "cli.rst") |
| 88 | + cli_dir = os.path.abspath(os.path.join(self.current_dir, "..", "remodel", "cli")) |
| 89 | + |
| 90 | + # Read the documentation file |
| 91 | + with open(docs_path, "r", encoding="utf-8") as f: |
| 92 | + content = f.read() |
| 93 | + |
| 94 | + # Find all python files in cli directory, excluding __init__.py |
| 95 | + cli_files = glob.glob(os.path.join(cli_dir, "*.py")) |
| 96 | + cli_modules = [ |
| 97 | + os.path.basename(f)[:-3] for f in cli_files if os.path.basename(f) != "__init__.py" # remove .py extension |
| 98 | + ] |
| 99 | + |
| 100 | + # Extract documented modules |
| 101 | + # Matches: .. automodule:: remodel.cli.module_name |
| 102 | + documented_modules = set() |
| 103 | + pattern = r"\.\.\s+automodule::\s+remodel\.cli\.(\w+)" |
| 104 | + |
| 105 | + for match in re.finditer(pattern, content): |
| 106 | + documented_modules.add(match.group(1)) |
| 107 | + |
| 108 | + missing_modules = [] |
| 109 | + for module in cli_modules: |
| 110 | + if module not in documented_modules: |
| 111 | + missing_modules.append(module) |
| 112 | + |
| 113 | + if missing_modules: |
| 114 | + self.fail( |
| 115 | + f"\nThe following CLI modules are present in remodel/cli/ but missing from cli.rst:\n" |
| 116 | + + "\n".join(f"- {mod}" for mod in missing_modules) |
| 117 | + + "\n\nPlease add them to docs/api/cli.rst." |
| 118 | + ) |
0 commit comments