Skip to content

Latest commit

 

History

History
338 lines (238 loc) · 8.77 KB

DOCUMENTATION.md

File metadata and controls

338 lines (238 loc) · 8.77 KB

Documentation Guide

This guide explains how to generate, verify, and maintain the documentation for the Terraform Provider WALLIX Bastion.

Overview

The documentation is generated using terraform-plugin-docs (tfplugindocs), which creates markdown files from templates and provider schema information.

Documentation Structure

├── docs/                           # Generated documentation (do not edit manually)
│   ├── index.md                   # Provider overview
│   ├── data-sources/              # Data source documentation
│   └── resources/                 # Resource documentation
├── templates/                     # Template files (edit these)
│   ├── index.md.tmpl             # Provider overview template
│   ├── data-sources/              # Data source templates
│   └── resources/                 # Resource templates
├── examples/                      # Example configurations
└── .tfplugindocs.yml             # Configuration file

Prerequisites

Install tfplugindocs

# Install using Go
go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest

# Or download from releases
# https://github.com/hashicorp/terraform-plugin-docs/releases

Install markdownlint (optional)

# Install using npm
npm install -g markdownlint-cli

# Or using yarn
yarn global add markdownlint-cli

Generating Documentation

1. Generate All Documentation

# From the repository root
tfplugindocs generate

This command will:

  • Export the provider schema
  • Generate missing templates for new resources/data sources
  • Render all templates to create final documentation in docs/

2. Generate Specific Documentation Types

# Generate only missing templates
tfplugindocs generate --rendered-provider-name="wallix-bastion" --rendered-website-dir="docs"

# Force regeneration of all content
tfplugindocs generate --force

3. Validate Documentation

# Validate templates and generation
tfplugindocs validate

# Check for missing templates
tfplugindocs generate --dry-run

Verifying Documentation Quality

1. Markdown Linting

# Check all documentation files
markdownlint docs/

# Auto-fix common issues
markdownlint docs/ --fix

# Check specific files
markdownlint docs/resources/application.md

2. Common Linting Rules

The documentation follows these markdown standards:

  • MD040: Fenced code blocks must specify language
  • MD032: Lists should be surrounded by blank lines
  • MD031: Code blocks should be surrounded by blank lines
  • MD047: Files should end with a newline
  • MD024: No duplicate headings at the same level
  • MD033: Avoid inline HTML (use markdown instead)
  • MD036: Don't use emphasis as headings

3. Manual Verification Checklist

  • All examples use valid Terraform syntax
  • Resource arguments are documented with correct types
  • Import examples are provided
  • Usage notes explain complex configurations
  • Best practices are included
  • Links to related resources are working

Working with Templates

Template Structure

Each template file follows this structure:

---
# generated by https://github.com/hashicorp/terraform-plugin-docs
page_title: "{{ .Name }} {{ .Type }} - {{ .ProviderName }}"
subcategory: ""
description: |-
  {{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
---

# {{ .Name }} ({{ .Type | title }})

{{ .Description }}

## Example Usage

```terraform
# Basic example
resource "wallix-bastion_resource" "example" {
  # configuration
}

{{ .SchemaMarkdown | trimspace }}

Import

terraform import wallix-bastion_resource.example "resource_id"
### Template Variables

- `{{ .Name }}`: Resource/data source name
- `{{ .Type }}`: "Resource" or "Data Source"
- `{{ .ProviderName }}`: Provider name
- `{{ .Description }}`: Resource description from schema
- `{{ .SchemaMarkdown }}`: Auto-generated schema documentation

### Best Practices for Templates

1. **Comprehensive Examples**: Include multiple real-world usage scenarios
2. **Progressive Complexity**: Start with basic examples, then show advanced usage
3. **Clear Descriptions**: Explain when and why to use specific configurations
4. **Security Considerations**: Document security implications and best practices
5. **Troubleshooting**: Include common issues and solutions
6. **Cross-References**: Link to related resources and data sources

## Documentation Workflow

### 1. Adding New Resources

When adding a new resource to the provider:

1. Create the resource implementation
2. Run `tfplugindocs generate` to create the template
3. Edit the generated template in `templates/resources/`
4. Add comprehensive examples and usage notes
5. Regenerate documentation: `tfplugindocs generate`
6. Verify with linting: `markdownlint docs/ --fix`

### 2. Updating Existing Documentation

1. Edit the template file in `templates/`
2. Regenerate: `tfplugindocs generate`
3. Verify changes in `docs/`
4. Run linting checks

### 3. Documentation Review Process

1. **Template Review**: Check template syntax and content
2. **Generation Test**: Ensure `tfplugindocs generate` runs without errors
3. **Linting Check**: Run `markdownlint docs/` to catch formatting issues
4. **Manual Review**: Verify examples are correct and complete
5. **Cross-Reference Check**: Ensure internal links work

## Configuration File

The `.tfplugindocs.yml` file controls documentation generation:

```yaml
provider_name: wallix-bastion
rendered_provider_name: wallix-bastion
rendered_website_dir: docs
examples_dir: examples

Troubleshooting

Common Issues

  1. Missing Templates Error

    Error: missing resource template file: templates/resources/new_resource.md.tmpl

    Solution: Run tfplugindocs generate to auto-create missing templates

  2. Schema Changes Not Reflected

    Error: schema documentation is outdated

    Solution: Rebuild the provider and regenerate documentation

  3. Markdown Linting Errors

    MD040/fenced-code-language Fenced code blocks should have a language specified

    Solution: Add language specifiers to code blocks (e.g., terraform, bash, json)

  4. Template Syntax Errors

    Error: template: parse error

    Solution: Check Go template syntax in the .md.tmpl files

Debug Commands

# Verbose output during generation
tfplugindocs generate --verbose

# Check provider schema
terraform providers schema -json > schema.json

# Validate template syntax
tfplugindocs validate

# Test specific template
tfplugindocs generate --rendered-provider-name="wallix-bastion" --examples-dir="examples" --website-temp-dir="tmp"

Continuous Integration

GitHub Actions Example

name: Documentation Check
on: [push, pull_request]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Go
        uses: actions/setup-go@v3
        with:
          go-version: '1.19'
          
      - name: Install tfplugindocs
        run: go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest
        
      - name: Generate documentation
        run: tfplugindocs generate
        
      - name: Check for changes
        run: |
          git diff --exit-code docs/ || (echo "Documentation needs to be regenerated" && exit 1)
          
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
          
      - name: Install markdownlint
        run: npm install -g markdownlint-cli
        
      - name: Lint documentation
        run: markdownlint docs/

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Generating documentation..."
tfplugindocs generate

echo "Linting documentation..."
markdownlint docs/ --fix

# Add any auto-fixed files
git add docs/

echo "Documentation check complete!"

Best Practices Summary

  1. Always edit templates, never generated docs directly
  2. Run tfplugindocs generate after template changes
  3. Use markdownlint --fix to maintain consistent formatting
  4. Include comprehensive examples for all use cases
  5. Document security considerations and best practices
  6. Test examples before committing
  7. Keep templates up-to-date with schema changes
  8. Review generated documentation for accuracy

Resources