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-sso
  • AWS-terraform-backend
  • AZURE-sa

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions