Deprecated: tfproviderdocs is no longer maintained. All functionality has
README
¶
tfproviderdocs
⚠️ Deprecated
tfproviderdocsis deprecated and no longer maintained. All functionality has been superseded by swissshepherd. Please migrate to swissshepherd; this repository will receive no further releases or bug fixes.
A documentation tool for Terraform Provider code.
Install
Local Install
Release binaries are available in the Releases section.
To instead use Go to install into your $GOBIN directory (e.g. $GOPATH/bin):
go install github.com/YakDriver/tfproviderdocs
Docker Install
docker pull moab4x/tfproviderdocs
Homebrew Install
brew install YakDriver/tap/tfproviderdocs
Usage
Additional information about usage and configuration options can be found by passing the help argument:
tfproviderdocs help
Local Usage
Change into the directory of the Terraform Provider code and run:
tfproviderdocs
Docker Usage
Change into the directory of the Terraform Provider code and run:
docker run -v $(pwd):/src moab4x/tfproviderdocs
Available Commands
check Command
The tfproviderdocs check command verifies the Terraform Provider documentation against the specifications from Terraform Registry documentation and common practices across official Terraform Providers. This includes the following checks:
- Verifies that no invalid directories are found in the documentation directory structure.
- Ensures that there is not a mix (legacy and Terraform Registry) of directory structures, which is not supported during Terraform Registry documentation ingress.
- Verifies number of documentation files is below Terraform Registry storage limits.
- Verifies all known data sources and resources have an associated documentation file (if
-providers-schema-jsonis provided) - Verifies no extraneous or incorrectly named documentation files exist (if
-providers-schema-jsonis provided) - Verifies each file in the documentation directories is valid.
The validity of files is checked with the following rules:
- Proper file extensions are used (e.g.
.mdfor Terraform Registry). - Verifies size of file is below Terraform Registry storage limits.
- YAML frontmatter can be parsed and matches expectations.
The YAML frontmatter checks include some defaults (e.g. no layout field for Terraform Registry), but there are some useful flags that can be passed to the command to tune the behavior, especially for larger Terraform Providers.
The validity of files can also be experimentally checked (via the -enable-contents-check flag) with the following rules:
- Ensures all expected headings are present.
- Verifies heading levels and text.
- Verifies schema attribute lists are ordered (if
-require-schema-orderingis provided). Only supports section level lists (not sub-section level lists) currently. - Verifies resource type is present in code blocks (e.g. examples and import sections).
For additional information about check flags, you can run tfproviderdocs check -help.
Development and Testing
This project uses Go Modules for dependency management.
Go Compatibility
This project follows the Go support policy for versions. The two latest major releases of Go are supported by the project.
Currently, that means Go 1.19 or later must be used when including this project as a dependency.
Updating Dependencies
Dependency updates are managed via Dependabot.
Unit Testing
go test ./...
Local Install Testing
go install .
Documentation
¶
Overview ¶
Command tfproviderdocs validates Terraform provider documentation.
Deprecated: tfproviderdocs is no longer maintained. All functionality has been superseded by swissshepherd. Please migrate to: https://github.com/YakDriver/swissshepherd
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package check verifies the structure and contents of Terraform Provider documentation directories and files.
|
Package check verifies the structure and contents of Terraform Provider documentation directories and files. |
|
contents
Package contents validates the body of individual Terraform Provider documentation files: headings, sections, schema attribute lists, and related content rules.
|
Package contents validates the body of individual Terraform Provider documentation files: headings, sections, schema attribute lists, and related content rules. |
|
Package command implements the tfproviderdocs CLI subcommands (check and version) consumed by main.
|
Package command implements the tfproviderdocs CLI subcommands (check and version) consumed by main. |
|
Package markdown provides Markdown parsing helpers (built on goldmark) used by the documentation checks.
|
Package markdown provides Markdown parsing helpers (built on goldmark) used by the documentation checks. |
|
Package version exposes build-time version information for tfproviderdocs.
|
Package version exposes build-time version information for tfproviderdocs. |