Update conftest-doc hook to use 'policy' directory by default and enhance documentation with output directory and template options

Author: jrottenberg

.pre-commit-hooks.yaml

@@ -40,8 +40,9 @@
 
 - id: conftest-doc
   name: Conftest Doc Policy Documentation
-  description: Generate policy documentation, fails if docs are out of date. Requires args with policy directory path.
+  description: Generate policy documentation, fails if docs are out of date. Defaults to policy directory. Supports -o for output directory and --template for custom template.
   entry: conftest doc
+  args: [policy]
   language: golang
   pass_filenames: false
   require_serial: true

docs/pre_commit.md

@@ -28,18 +28,25 @@ your Rego policies. It runs `conftest doc` and if the generated documentation
 differs from what's committed, pre-commit will fail. The updated documentation
 files are written, so you can simply stage them and re-commit.
 
-**Important:** You must specify the policy directory via `args` - this hook
-requires at least one directory path argument.
+By default, the hook documents the `policy` directory. Specifying `args`
+replaces the default, so you must include the policy directory path.
 
 ```yaml
 repos:
   - repo: https://github.com/open-policy-agent/conftest
     rev: v0.64.0
     hooks:
       - id: conftest-doc
-        args: [path/to/your/policies]  # Required: policy directory to document
+        # Uses 'policy' directory by default, or specify your own:
+        # args: [path/to/your/policies]
         # To specify an output directory, use -o:
         # args: [-o, docs/, path/to/your/policies]
+        # To use a custom template, use --template:
+        # args: [--template, path/to/template.md, path/to/your/policies]
+        # Combined example:
+        # args: [-o, docs/, --template, path/to/template.md, path/to/your/policies]
+        # To only run when .rego files in a specific directory change:
+        # files: ^path/to/your/policies/.*\.rego$
 ```
 
 ## Additional Hooks