docs(azure-policy-assignments): update docs and added examples

[pablosanchezpaz]

No description provided.

[pablosanchezpaz]

Related to #786

[Copilot]

Pull request overview

Updates the Azure Policy Assignments module documentation and adds a basic example, with terraform-docs configuration to generate/inject README content.

Changes:

• Added terraform-docs header/footer files and config for README injection.
• Added a “basic” example (HCL + YAML values) demonstrating policy assignments.
• Expanded README with generated docs sections and links to examples/resources.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
modules/azure-policy-assignments/docs/header.md	Adds module overview + full YAML/HCL usage examples for terraform-docs header.
modules/azure-policy-assignments/docs/footer.md	Adds example links and support/resource references for terraform-docs footer.
modules/azure-policy-assignments/_examples/basic/values.yaml	Adds basic YAML example inputs for assignments.
modules/azure-policy-assignments/_examples/basic/main.tf	Adds basic Terraform module usage example.
modules/azure-policy-assignments/README.MD	Injects/contains terraform-docs generated content including the new header/footer and module docs.
modules/azure-policy-assignments/.terraform-docs.yml	Adds terraform-docs configuration to generate README from header/footer + module metadata.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The example resource_id contains vaults/-test, which is not a valid Key Vault resource ID format and will cause the example to fail if copied. Replace it with the correct vault name segment (e.g., .../vaults/test).

Suggested change

	resource_id = "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/-test"
	resource_id = "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/test"

[Copilot]

Same issue as in docs/header.md: the README’s HCL example includes an invalid Key Vault resource ID (vaults/-test). Update it to a valid resource ID so the documented example is copy/paste runnable.

Suggested change

	resource_id = "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/-test"
	resource_id = "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/test"

[Copilot]

The YAML example defines two assignments with the same name (example-assignment-2) at the same scope. Azure Policy assignment names must be unique at a given scope, so this example is likely to fail or mislead users. Use distinct names (or collapse into a single example showing either resource_group_id or resource_group_name).

[Copilot]

The header YAML example nests assignments under values:, but the added example file _examples/basic/values.yaml uses assignments: at the root. This inconsistency can confuse users about the expected input shape—consider aligning the documentation with the actual example format (or explicitly explaining when/why values: is required).

Suggested change

	values:
	assignments:
	- name: "example-assignment-3"
	policy_type: "custom"
	policy_name: "Example Policy"
	resource_id: "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/test"
	scope: "resource"
	- name: "example-assignment-2"
	policy_type: "builtin"
	policy_name: "Allowed virtual machine size SKUs"
	resource_group_id: "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test"
	scope: "resource group"
	- name: "example-assignment-2"
	policy_type: "builtin"
	policy_name: "Allowed virtual machine size SKUs"
	resource_group_name: "test"
	scope: "resource group"
	- name: "example-assignment-1"
	policy_type: "builtin"
	policy_name: "Allowed locations"
	scope: "subscription"
	- name: "example-assignment-4"
	policy_type: "custom"
	policy_name: "Example Policy"
	management_group_name: "example"
	scope: "management group"
	assignments:
	- name: "example-assignment-3"
	policy_type: "custom"
	policy_name: "Example Policy"
	resource_id: "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test/providers/Microsoft.KeyVault/vaults/test"
	scope: "resource"
	- name: "example-assignment-2"
	policy_type: "builtin"
	policy_name: "Allowed virtual machine size SKUs"
	resource_group_id: "/subscriptions/2de29132-986f-482d-a49f-31441fc7992b/resourceGroups/test"
	scope: "resource group"
	- name: "example-assignment-2"
	policy_type: "builtin"
	policy_name: "Allowed virtual machine size SKUs"
	resource_group_name: "test"
	scope: "resource group"
	- name: "example-assignment-1"
	policy_type: "builtin"
	policy_name: "Allowed locations"
	scope: "subscription"
	- name: "example-assignment-4"
	policy_type: "custom"
	policy_name: "Example Policy"
	management_group_name: "example"
	scope: "management group"

[Copilot]

The basic example currently shows subscription + resource group assignments, but does not include a management group assignment. Update the description to match the actual example content, or extend the example to include a management group assignment.

Suggested change

	- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-policy-assignments/_examples/basic) - Policy assignments at subscription, resource group and management group scopes.
	- [basic](https://github.com/prefapp/tfm/tree/main/modules/azure-policy-assignments/_examples/basic) - Policy assignments at subscription and resource group scopes.

[Copilot]

An empty version field is ambiguous and can make docs generation less reproducible across environments. Prefer removing the field entirely or pinning/setting an explicit terraform-docs version constraint to ensure consistent README output.

Suggested change

version: ""