first commit

utils/check_modeling_rules_doc.py

@@ -0,0 +1,124 @@
+# Copyright 2026 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Keep `## Rules reference` section of docs/source/en/modeling_rules.md in sync
+with the rules defined in utils/rules.toml via the installed mlinter package.
+
+Usage (from the root of the repo):
+
+Check everything is up to date (used in ``make check-repo``):
+
+```bash
+python utils/check_modeling_rules_doc.py
+```
+
+Auto-regenerate if out of date (used in ``make fix-repo``):
+
+```bash
+python utils/check_modeling_rules_doc.py --fix_and_overwrite
+```
+"""
+
+import argparse
+from pathlib import Path
+
+
+CHECKER_CONFIG = {
+    "name": "modeling_rules_doc",
+    "label": "Modeling rules documentation",
+    # Depends on utils/rules.toml plus the installed `mlinter` package output,
+    # which cannot be fully expressed as repo cache globs for the checker cache.
+    "cache_globs": None,
+    "check_args": ["--rules-toml", "utils/rules.toml"],
+    "fix_args": ["--rules-toml", "utils/rules.toml", "--fix_and_overwrite"],
+}
+
+ROOT = Path(__file__).resolve().parent.parent
+DOC_PATH = ROOT / "docs" / "source" / "en" / "modeling_rules.md"
+RULES_TOML_PATH = ROOT / "utils" / "rules.toml"
+
+BEGIN_MARKER = "<!-- BEGIN RULES REFERENCE -->"
+END_MARKER = "<!-- END RULES REFERENCE -->"
+
+
+def _require_mlinter():
+    try:
+        import mlinter
+        from mlinter import mlinter as mlinter_impl
+    except ModuleNotFoundError as error:
+        raise ModuleNotFoundError(
+            "This script requires the standalone `transformers-mlinter` package. "
+            'Install the repo quality dependencies with `pip install -e ".[quality]"` and retry.'
+        ) from error
+
+    return mlinter, mlinter_impl
+
+
+def _resolve_path(path: Path) -> Path:
+    return path if path.is_absolute() else ROOT / path
+
+
+def generate_rules_reference(rule_specs_path: Path = RULES_TOML_PATH) -> str:
+    mlinter, mlinter_impl = _require_mlinter()
+    # Reuse mlinter's registry-switching helper so docs rendering reflects the repo-local rule file.
+    with mlinter_impl._using_rule_specs(_resolve_path(rule_specs_path)):
+        return mlinter.render_rules_reference()
+
+
+def check_modeling_rules_doc(overwrite: bool = False, rule_specs_path: Path = RULES_TOML_PATH):
+    with DOC_PATH.open(encoding="utf-8") as f:
+        content = f.read()
+
+    begin_idx = content.find(BEGIN_MARKER)
+    end_idx = content.find(END_MARKER)
+    if begin_idx == -1 or end_idx == -1:
+        raise ValueError(
+            f"Could not find {BEGIN_MARKER} and {END_MARKER} markers in {DOC_PATH}. "
+            "These markers delimit the auto-generated rules reference section."
+        )
+
+    after_begin = begin_idx + len(BEGIN_MARKER)
+    expected = "\n\n" + generate_rules_reference(rule_specs_path) + "\n"
+    current = content[after_begin:end_idx]
+
+    if current == expected:
+        return
+
+    if overwrite:
+        new_content = content[:after_begin] + expected + content[end_idx:]
+        with DOC_PATH.open("w", encoding="utf-8") as f:
+            f.write(new_content)
+        print(f"Updated rules reference in {DOC_PATH}")
+    else:
+        raise ValueError(
+            "The rules reference section in docs/source/en/modeling_rules.md is out of sync "
+            "with utils/rules.toml. Run `make fix-repo` to regenerate it."
+        )
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--rules-toml",
+        type=Path,
+        default=RULES_TOML_PATH,
+        help="Path to a rules TOML file. Defaults to utils/rules.toml.",
+    )
+    parser.add_argument("--fix_and_overwrite", action="store_true", help="Whether to fix inconsistencies.")
+    args = parser.parse_args()
+
+    try:
+        check_modeling_rules_doc(args.fix_and_overwrite, args.rules_toml)
+    except ModuleNotFoundError as error:
+        raise SystemExit(str(error)) from error