test(punctuation): guard SenseVoice documentation on exact PR heads

Signed-off-by: zhifu gao <[email protected]>

.github/workflows/test-punctuation-docs.yml

@@ -0,0 +1,32 @@
+name: Validate punctuation documentation
+
+on:
+  pull_request:
+    paths:
+      - 'funasr/models/ct_transformer/model.py'
+      - 'tests/test_ct_transformer_docs.py'
+      - '.github/workflows/test-punctuation-docs.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'funasr/models/ct_transformer/model.py'
+      - 'tests/test_ct_transformer_docs.py'
+      - '.github/workflows/test-punctuation-docs.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  docs-contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Check punctuation guidance without model dependencies
+        run: python tests/test_ct_transformer_docs.py -v

tests/test_ct_transformer_docs.py

@@ -0,0 +1,25 @@
+"""Check punctuation API guidance without importing the model or its dependencies."""
+
+import ast
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class CTTransformerDocsContract(unittest.TestCase):
+    def test_unpunctuated_sensevoice_output_can_use_punctuation_model(self):
+        path = ROOT / "funasr/models/ct_transformer/model.py"
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+        model = next(node for node in tree.body
+                     if isinstance(node, ast.ClassDef) and node.name == "CTTransformer")
+        doc = " ".join(ast.get_docstring(model).split())
+        self.assertIn("unpunctuated SenseVoiceSmall", doc)
+        self.assertIn("configure punc_model", doc)
+        self.assertIn("when punctuation is needed", doc)
+        self.assertNotIn("Only required for Paraformer", doc)
+
+
+if __name__ == "__main__":
+    unittest.main()