Skip to content

Align the documentation of the tf modules #786

@jotasixto

Description

@jotasixto

Motivation

We need to have a common documentation format for all the modules we publish and maintain.

To do this, we will align the README.md file of all modules in this repository with this format:

# <Azure-AWS> <resource-name> Terraform Module

## Overview

 <summary>

## Key Features

- **<Feature 1>**: <description>
- **<Feature 2>**: <description>
- **<Feature 3>**: <description>

## Basic Usage

### <Description usage 1>

``hcl

``

### <Description usage 2>

``hcl

``

<terraform-docs generate>

## Examples

For detailed examples, refer to the [module examples](https://github.com/prefapp/tfm/tree/main/modules/<module-name>/_examples):

- [<Example 1>](https://github.com/prefapp/tfm/tree/main/modles/<module-name>/_examples/example1) - Example 1 description
- [<Example 2>](https://github.com/prefapp/tfm/tree/main/modles/<module-name>/_examples/example2) - Example 2 description

## Remote resources

- **<remote resource 1>**: [<remote URL 1>]
- **<remote resource 2>**: [<remote URL 2>]

## Support

For issues, questions, or contributions related to this module, please visit the [repository's issue tracker](https://github.com/prefapp/tfm/issues).

The Terraform Docs configuration file to be included in the modules is this:

formatter: "markdown" # this is required

version: ""

header-from: docs/header.md
footer-from: docs/footer.md

recursive:
  enabled: false
  path: modules
  include-main: true

sections:
  hide: []
  show: []

content: ""

output:
  file: "README.md"
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

output-values:
  enabled: false
  from: ""

sort:
  enabled: true
  by: name

settings:
  anchor: true
  color: true
  default: true
  description: false
  escape: true
  hide-empty: false
  html: true
  indent: 2
  lockfile: true
  read-comments: true
  required: true
  sensitive: true
  type: true

Scope

We prioritize AWS modules, but to complete this task we need to have all modules aligned.
We also took advantage of this task to add a contribution guide where we explain how to maintain the structure of a new module as well as this documentation format.

Acceptance criteria(DOD):

  • All Terraform modules have aligned documentation
  • Defined guide for contributing to the project

List of TF to prepare:

  • AWS-cloudfront-delivery
  • AWS-ECS
  • AWS-EKS
  • AWS-OIDC
  • AWS-parameter-store
  • AWS-RDS
  • AWS-SSO
  • AWS-terraform-backend
  • azure-vnet-and-subnet
  • azure-vmss
  • azure-sa
  • azure-sa-backup
  • azure-role-assignment
  • azure-redis-cache
  • azure-public-prefix
  • azure-policy-definitions
  • azure-policy-assignments
  • azure-mi
  • azure-oidc
  • azure-nsg-nsr
  • azure-flexible-server-postgresql
  • azure-event-hub
  • azure-customrole
  • azure-kv

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions