A Terraform provider for Dokploy
Plugin-framework provider covering projects, environments, applications, Compose stacks, managed databases, domains, mounts, ports, redirects, basic auth, registries, SSH keys, certificates and backup destinations, over Dokploy's tRPC-over-REST API. The shim package exposes the provider to other Go modules, which is how pulumi-dokploy bridges it.
This commit is contained in:
67
.agents/skills/provider-docs/SKILL.md
Normal file
67
.agents/skills/provider-docs/SKILL.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: provider-docs
|
||||
description: Create, update, and review Terraform provider documentation for Terraform Registry using HashiCorp-recommended patterns, tfplugindocs templates, and schema descriptions. Use when adding or changing provider configuration, resources, data sources, ephemeral resources, list resources, functions, or guides; when validating generated docs; and when troubleshooting missing or incorrect Registry documentation.
|
||||
---
|
||||
|
||||
# Terraform Provider Docs
|
||||
|
||||
## Follow This Workflow
|
||||
|
||||
1. Confirm scope and documentation targets.
|
||||
- Map code changes to the exact doc targets: provider index, resources, data sources, ephemeral resources, list resources, functions, or guides.
|
||||
- Decide whether content should come from schema descriptions, templates, or both.
|
||||
|
||||
2. Write schema descriptions first.
|
||||
- Add precise user-facing descriptions to schema fields so generated docs stay aligned with behavior.
|
||||
- Keep wording specific to argument purpose, constraints, defaults, and computed behavior.
|
||||
|
||||
3. Add or update template files in `docs/`.
|
||||
- Create only files that map to implemented provider objects.
|
||||
- Use HashiCorp-recommended template paths:
|
||||
- `docs/index.md.tmpl`
|
||||
- `docs/data-sources/<name>.md.tmpl`
|
||||
- `docs/resources/<name>.md.tmpl`
|
||||
- `docs/ephemeral-resources/<name>.md.tmpl`
|
||||
- `docs/list-resources/<name>.md.tmpl`
|
||||
- `docs/functions/<name>.md.tmpl`
|
||||
- `docs/guides/<name>.md.tmpl`
|
||||
- Keep templates focused on overview and examples; rely on generated sections for field-by-field details.
|
||||
|
||||
4. Generate documentation with `tfplugindocs`.
|
||||
- Prefer repository defaults when configured:
|
||||
```bash
|
||||
go generate ./...
|
||||
```
|
||||
- Otherwise run the generator directly:
|
||||
```bash
|
||||
go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
|
||||
```
|
||||
- Re-run generation after every schema or template edit.
|
||||
|
||||
5. Validate the generated markdown.
|
||||
- Verify files in `docs/` match the current provider implementation.
|
||||
- Verify examples are valid HCL and reflect current argument/attribute names.
|
||||
- Verify required/optional/computed semantics in docs match schema behavior.
|
||||
|
||||
6. Apply Registry publication rules before release.
|
||||
- Use semantic version tags prefixed with `v` (for example `v1.2.3`).
|
||||
- Create release tags from the default branch.
|
||||
- Keep `terraform-registry-manifest.json` in the repository root.
|
||||
- Expect docs to be versioned in Registry and switchable with the version selector.
|
||||
|
||||
7. Preview or troubleshoot publication when needed.
|
||||
- Use the HashiCorp preview process to inspect rendered docs before release when accuracy risk is high.
|
||||
- If docs are missing in Registry, check tag format, tag source branch, manifest file presence, and provider publication status.
|
||||
|
||||
## Enforce Quality Bar
|
||||
|
||||
- Keep documentation behaviorally accurate; never describe unsupported arguments or attributes.
|
||||
- Keep examples minimal, realistic, and runnable.
|
||||
- Keep terminology and naming consistent across provider, resources, and data sources.
|
||||
- Avoid duplicating generated argument/attribute blocks in manual templates.
|
||||
- Keep doc changes tied to the same PR as schema/API changes whenever possible.
|
||||
|
||||
## Load References On Demand
|
||||
|
||||
- Read `references/hashicorp-provider-docs.md` for source-backed rules and official links.
|
||||
- Load only the sections needed for the current change to keep context lean.
|
||||
7
.agents/skills/provider-docs/agents/openai.yaml
Normal file
7
.agents/skills/provider-docs/agents/openai.yaml
Normal file
@@ -0,0 +1,7 @@
|
||||
# Copyright IBM Corp. 2025, 2026
|
||||
# SPDX-License-Identifier: MPL-2.0
|
||||
|
||||
interface:
|
||||
display_name: "Terraform Provider Docs"
|
||||
short_description: "Best practices for Terraform provider docs"
|
||||
default_prompt: "Use $terraform-provider-docs to create or update Terraform Registry provider documentation with HashiCorp-aligned structure and style."
|
||||
@@ -0,0 +1,65 @@
|
||||
# HashiCorp Provider Documentation Reference
|
||||
|
||||
Source of truth for this skill:
|
||||
- https://developer.hashicorp.com/terraform/registry/providers/docs
|
||||
|
||||
## Core Rules
|
||||
|
||||
- Publish provider docs through Terraform Registry using `tfplugindocs`.
|
||||
- Generate provider docs from schema descriptions and markdown templates.
|
||||
- Store templates under the repository `docs/` directory with expected naming conventions.
|
||||
- Keep release tags and manifest metadata valid so Registry can render and display docs.
|
||||
|
||||
## Template Paths
|
||||
|
||||
Use these template paths when the corresponding provider objects exist:
|
||||
|
||||
- `docs/index.md.tmpl`
|
||||
- `docs/data-sources/<name>.md.tmpl`
|
||||
- `docs/resources/<name>.md.tmpl`
|
||||
- `docs/ephemeral-resources/<name>.md.tmpl`
|
||||
- `docs/list-resources/<name>.md.tmpl`
|
||||
- `docs/functions/<name>.md.tmpl`
|
||||
- `docs/guides/<name>.md.tmpl`
|
||||
|
||||
## Generation Workflow
|
||||
|
||||
HashiCorp recommends wiring generator execution through `go generate`:
|
||||
|
||||
```go
|
||||
//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
|
||||
```
|
||||
|
||||
Run from repository root:
|
||||
|
||||
```bash
|
||||
go generate ./...
|
||||
```
|
||||
|
||||
Alternative direct execution:
|
||||
|
||||
```bash
|
||||
go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --provider-name <provider_name>
|
||||
```
|
||||
|
||||
## Release and Publication Constraints
|
||||
|
||||
- Use semantic version tags prefixed with `v`.
|
||||
- Create tags from the default branch.
|
||||
- Keep `terraform-registry-manifest.json` in the repository root.
|
||||
- Understand docs appear by provider version in Registry once the provider release is published.
|
||||
|
||||
## Preview and Troubleshooting
|
||||
|
||||
- Use HashiCorp's preview process to verify rendering before release when needed.
|
||||
- If docs are missing or stale in Registry, verify:
|
||||
- tag naming and tag branch source
|
||||
- manifest file presence and validity
|
||||
- provider version publication state
|
||||
|
||||
## Related Canonical Pages
|
||||
|
||||
- Provider docs guidance:
|
||||
- https://developer.hashicorp.com/terraform/registry/providers/docs
|
||||
- Terraform Plugin Docs (`tfplugindocs`) source and usage:
|
||||
- https://github.com/hashicorp/terraform-plugin-docs
|
||||
Reference in New Issue
Block a user