diff --git a/.github/actions/build-website/action.yml b/.github/actions/build-website/action.yml index 0e1036c76..eddb5804c 100644 --- a/.github/actions/build-website/action.yml +++ b/.github/actions/build-website/action.yml @@ -90,10 +90,15 @@ runs: tag: v0.18.0 cache: enable + - name: Install Atmos + uses: cloudposse/github-action-setup-atmos@v2 + with: + install-wrapper: false + - name: "Render Documentation for Terraform Components" shell: bash env: - PUBLIC_REPO_ACCESS_TOKEN: ${{ inputs.repo_access_token }} + PUBLIC_REPO_ACCESS_TOKEN: ${{ inputs.repo_access_token }} run: | ./scripts/render-docs-for-components.sh diff --git a/.gitignore b/.gitignore index c5986d3b7..bbb89ac55 100644 --- a/.gitignore +++ b/.gitignore @@ -103,3 +103,7 @@ content/reference-architecture/** !content/components/library/aws/_category_.json !content/github-actions/library/actions/_category_.json changelog/* + +.atmos +.python-version +yarn.lock diff --git a/Makefile b/Makefile index 1f55b952d..cf6c28273 100644 --- a/Makefile +++ b/Makefile @@ -40,3 +40,9 @@ real-clean: lint: npx docusaurus-mdx-checker --cwd docs + +readme/build: + @atmos docs generate readme + +readme: + @atmos docs generate readme diff --git a/README.md b/README.md index e294af17d..00851050a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,11 @@ # Developer Documentation -Latest ReleaseSlack Community + + +Latest ReleaseSlack CommunityGet Support + + -## Makefile Targets -```text -Available targets: - help Help screen - help/all Display help for all targets - help/short This help short screen -``` - + ## Related Projects @@ -100,6 +96,38 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. **NOTE:** Be sure to merge the latest changes from "upstream" before making a pull request! + +## Running Terraform Tests + +We use [Atmos](https://atmos.tools) to streamline how Terraform tests are run. It centralizes configuration and wraps common test workflows with easy-to-use commands. + +All tests are located in the [`test/`](test) folder. + +Under the hood, tests are powered by Terratest together with our internal [Test Helpers](https://github.com/cloudposse/test-helpers) library, providing robust infrastructure validation. + +Setup dependencies: +- Install Atmos ([installation guide](https://atmos.tools/install/)) +- Install Go [1.24+ or newer](https://go.dev/doc/install) +- Install Terraform or OpenTofu + +To run tests: + +- Run all tests: + ```sh + atmos test run + ``` +- Clean up test artifacts: + ```sh + atmos test clean + ``` +- Explore additional test options: + ```sh + atmos test --help + ``` +The configuration for test commands is centrally managed. To review what's being imported, see the [`atmos.yaml`](https://raw.githubusercontent.com/cloudposse/.github/refs/heads/main/.github/atmos/terraform-module.yaml) file. + +Learn more about our [automated testing in our documentation](https://docs.cloudposse.com/community/contribute/automated-testing/) or implementing [custom commands](https://atmos.tools/core-concepts/custom-commands/) with atmos. + ### 🌎 Slack Community Join our [Open Source Community](https://cpco.io/slack?utm_source=github&utm_medium=readme&utm_campaign=cloudposse/docs&utm_content=slack) on Slack. It's **FREE** for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totally *sweet* infrastructure. @@ -137,7 +165,7 @@ All other trademarks referenced herein are the property of their respective owne --- -Copyright © 2017-2024 [Cloud Posse, LLC](https://cpco.io/copyright) +Copyright © 2017-2025 [Cloud Posse, LLC](https://cpco.io/copyright) README footer diff --git a/README.yaml b/README.yaml index c8e9bd267..38be0c3fd 100644 --- a/README.yaml +++ b/README.yaml @@ -21,9 +21,6 @@ description: |- Let's jump right in! Here's how to get started with our documentation. -include: - - "docs/targets.md" - usage: |- 1. Build dependencies ``` diff --git a/atmos.yaml b/atmos.yaml new file mode 100644 index 000000000..f71a061f1 --- /dev/null +++ b/atmos.yaml @@ -0,0 +1,12 @@ +# Atmos Configuration — powered by https://atmos.tools +# +# This configuration enables centralized, DRY, and consistent project scaffolding using Atmos. +# +# Included features: +# - Organizational custom commands: https://atmos.tools/core-concepts/custom-commands +# - Automated README generation: https://atmos.tools/cli/commands/docs/generate +# + +# Import shared configuration used by all modules +import: + - https://raw.githubusercontent.com/cloudposse/.github/refs/heads/main/.github/atmos/default.yaml diff --git a/package-lock.json b/package-lock.json index b175eede2..1aa665eec 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6686,8 +6686,8 @@ "license": "MIT" }, "node_modules/custom-loaders": { - "version": "0.0.0", - "resolved": "file:plugins/custom-loaders" + "resolved": "plugins/custom-loaders", + "link": true }, "node_modules/cytoscape": { "version": "3.30.1", @@ -19365,6 +19365,9 @@ "type": "github", "url": "https://github.com/sponsors/wooorm" } + }, + "plugins/custom-loaders": { + "version": "0.0.0" } } } diff --git a/scripts/docs-collator/AbstractFetcher.py b/scripts/docs-collator/AbstractFetcher.py index bb4045db7..648df0250 100644 --- a/scripts/docs-collator/AbstractFetcher.py +++ b/scripts/docs-collator/AbstractFetcher.py @@ -3,6 +3,7 @@ DOCS_DIR = "docs" TARGETS_MD = "targets.md" README_YAML = "README.yaml" +ATMOS_YAML = "atmos.yaml" class MissingReadmeYamlException(Exception): @@ -29,3 +30,7 @@ def _fetch_docs(self, repo, module_download_dir, submodule_dir=""): continue self.github_provider.fetch_file(repo, remote_file, module_download_dir) + + def _fetch_atmos_yaml(self, repo, module_download_dir): + self.github_provider.fetch_file(repo, ATMOS_YAML, module_download_dir) + diff --git a/scripts/docs-collator/GitHubActionFetcher.py b/scripts/docs-collator/GitHubActionFetcher.py index b30072686..6ce972877 100644 --- a/scripts/docs-collator/GitHubActionFetcher.py +++ b/scripts/docs-collator/GitHubActionFetcher.py @@ -6,6 +6,7 @@ ACTIONS_DIR = "actions" README_YAML = "README.yaml" README_MD = "README.md" +ACTION_YAML = "action.yml" class GitHubActionFetcher(AbstractFetcher): @@ -23,12 +24,19 @@ def fetch(self, repo): self._fetch_readme_yaml(repo, repo_download_dir) + self._fetch_action_yaml(repo, repo_download_dir) + + self._fetch_atmos_yaml(repo, repo_download_dir) + if DOCS_DIR in remote_files: self._fetch_docs(repo, repo_download_dir) if ACTIONS_DIR in remote_files: self.__fetch_sub_actions(repo, repo_download_dir) + def _fetch_action_yaml(self, repo, module_download_dir): + self.github_provider.fetch_file(repo, ACTION_YAML, module_download_dir) + def __fetch_sub_actions(self, repo, module_download_dir): remote_files = self.github_provider.list_repo_dir(repo, ACTIONS_DIR) diff --git a/scripts/docs-collator/GitHubActionRenderer.py b/scripts/docs-collator/GitHubActionRenderer.py index 2a0a0e6ab..1ba64a6eb 100644 --- a/scripts/docs-collator/GitHubActionRenderer.py +++ b/scripts/docs-collator/GitHubActionRenderer.py @@ -7,10 +7,9 @@ from utils import rendering, templating TARGETS_MD = "targets.md" -README_YAML = "README.yaml" README_MD = "README.md" +ATMOS_YAML = "atmos.yaml" INDEX_CATEGORY_JSON = "_category_.json" -README_TEMPLATE = "readme.md" DOC_SUBFOLDER = "actions" SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__)) @@ -45,25 +44,26 @@ def render(self, repo): self._copy_extra_resources_for_docs(repo_download_dir, module_docs_dir) def __render_readme(self, module_download_dir, module_docs_dir): - readme_yaml_file = os.path.join(module_download_dir, README_YAML) readme_md_file = os.path.join(module_download_dir, README_MD) - readme_tmpl_file = os.path.join(TEMPLATES_DIR, README_TEMPLATE) + atmos_yaml_file = os.path.join(TEMPLATES_DIR, ATMOS_YAML) io.create_dirs(module_docs_dir) response = subprocess.run( [ - "make", + "atmos", + "--config", + f"{atmos_yaml_file}", + "docs", + "generate", "readme", - f"README_TEMPLATE_FILE={readme_tmpl_file}", - f"README_FILE={readme_md_file}", - f"README_YAML={readme_yaml_file}", - f"README_TEMPLATE_YAML={readme_yaml_file}", - f"README_INCLUDES={module_download_dir}", ], capture_output=True, + cwd=module_download_dir, ) + logging.info(response.stderr.decode("utf-8")) + if response.returncode != 0: error_message = response.stderr.decode("utf-8") raise TerraformDocsRenderingError(error_message) diff --git a/scripts/docs-collator/ModuleFetcher.py b/scripts/docs-collator/ModuleFetcher.py index f9c6d8ace..d1e207140 100644 --- a/scripts/docs-collator/ModuleFetcher.py +++ b/scripts/docs-collator/ModuleFetcher.py @@ -1,6 +1,7 @@ import os from AbstractFetcher import AbstractFetcher, MissingReadmeYamlException +import logging DOCS_DIR = "docs" IMAGES_DIR = "images" @@ -56,12 +57,15 @@ def __fetch_submodules(self, repo, module_download_dir): for readme_file in readme_files.values(): self.github_provider.fetch_file(repo, readme_file, module_download_dir) if os.path.basename(readme_file) == README_YAML: + logging.info(f"Fetching submodule docs for: {os.path.dirname(readme_file)}") self._fetch_docs( repo, module_download_dir, submodule_dir=os.path.dirname(readme_file), ) + self.__fetch_terraform_files(repo, module_download_dir, remote_files) + def __fetch_terraform_files(self, repo, module_download_dir, remote_files): for remote_file in remote_files: # We only need variables and output files to render terraform-docs. diff --git a/scripts/docs-collator/ModuleRenderer.py b/scripts/docs-collator/ModuleRenderer.py index 616aa5c62..6ea1d21b0 100644 --- a/scripts/docs-collator/ModuleRenderer.py +++ b/scripts/docs-collator/ModuleRenderer.py @@ -9,11 +9,10 @@ DOCS_DIR = "docs" IMAGES_DIR = "images" SUBMODULES_DIR = "modules" -TARGETS_MD = "targets.md" +ATMOS_YAML = "atmos.yaml" README_YAML = "README.yaml" README_MD = "README.md" INDEX_CATEGORY_JSON = "_category_.json" -MODULES_README_TEMPLATE = "readme.md" SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__)) TEMPLATES_DIR = os.path.join(SCRIPT_DIR, "templates/modules") @@ -59,45 +58,44 @@ def render(self, repo): # self.__create_index_for_provider(repo) # self.__create_indexes_for_subfolders(repo) - def __render_readme(self, module_download_dir, module_docs_dir): + def __render_readme(self, module_download_dir, module_docs_dir, template_name="readme"): readme_yaml_file = os.path.join(module_download_dir, README_YAML) readme_md_file = os.path.join(module_download_dir, README_MD) - readme_tmpl_file = os.path.join(TEMPLATES_DIR, MODULES_README_TEMPLATE) + atmos_yaml_file = os.path.join(TEMPLATES_DIR, ATMOS_YAML) io.create_dirs(module_docs_dir) - # Re-render terraform docs with this repo's terraform-docs template for modules. - # This replaces docs/terraform.md for the given module in place - logging.debug(f"Rendering terraform docs for: {module_download_dir}") - rendering.render_terraform_docs( - module_download_dir, os.path.join(TEMPLATES_DIR, "terraform-docs.yml") - ) - # Run the make readme command in the module directory to compile README.md logging.debug(f"Rendering README.md for: {module_download_dir}") - logging.debug(f"make readme") - logging.debug(f"README_TEMPLATE_FILE: {readme_tmpl_file}") + logging.debug(f"atmos docs generate readme --config {atmos_yaml_file}") + logging.debug(f"ATMOS_YAML_FILE: {atmos_yaml_file}") logging.debug(f"README_FILE: {readme_md_file}") logging.debug(f"README_YAML: {readme_yaml_file}") - logging.debug(f"README_TEMPLATE_YAML: {readme_yaml_file}") - logging.debug(f"README_INCLUDES: {module_download_dir}") + logging.debug(f"README_MD: {readme_md_file}") response = subprocess.run( [ - "make", - "readme", - f"README_TEMPLATE_FILE={readme_tmpl_file}", - f"README_FILE={readme_md_file}", - f"README_YAML={readme_yaml_file}", - f"README_TEMPLATE_YAML={readme_yaml_file}", - f"README_INCLUDES={module_download_dir}", + "atmos", + "--config", + f"{atmos_yaml_file}", + "docs", + "generate", + template_name, ], capture_output=True, + cwd=module_download_dir, ) if response.returncode != 0: error_message = response.stderr.decode("utf-8") raise TerraformDocsRenderingError(error_message) + # Re-render terraform docs with this repo's terraform-docs template for modules. + # This replaces docs/terraform.md for the given module in place + logging.debug(f"Rendering terraform docs for: {module_download_dir}") + rendering.render_terraform_docs( + module_download_dir, os.path.join(TEMPLATES_DIR, "terraform-docs.yml") + ) + logging.info(f"Rendered: {readme_md_file}") def __copy_extra_resources_for_images(self, module_download_dir, module_docs_dir): @@ -143,7 +141,7 @@ def __copy_extra_resources_for_submodules( submodule_dir = os.path.dirname(readme) readme_md = os.path.join(submodule_dir, README_MD) self._pre_rendering_fixes(repo, module_download_dir, rel_dir) - self.__render_readme(submodule_dir, dest_dir) + self.__render_readme(submodule_dir, dest_dir, "submodule-readme") self._post_rendering_fixes(repo, readme_md, rel_dir) io.copy_file(readme_md, os.path.join(dest_dir, README_MD)) continue diff --git a/scripts/docs-collator/component/fetcher.py b/scripts/docs-collator/component/fetcher.py index 49c28d5d0..fc5cf4a85 100644 --- a/scripts/docs-collator/component/fetcher.py +++ b/scripts/docs-collator/component/fetcher.py @@ -26,6 +26,7 @@ def fetch(self, repo): self._fetch_readme_yaml(repo, module_download_dir) self._fetch_readme_md(repo, module_download_dir) + self._fetch_atmos_yaml(repo, module_download_dir) if CHANGELOG_MD in remote_files: self._fetch_changelog_md(repo, module_download_dir) diff --git a/scripts/docs-collator/component/renderer/templates/components/yml/atmos.yaml b/scripts/docs-collator/component/renderer/templates/components/yml/atmos.yaml new file mode 100644 index 000000000..45f67ccf0 --- /dev/null +++ b/scripts/docs-collator/component/renderer/templates/components/yml/atmos.yaml @@ -0,0 +1,19 @@ +docs: + generate: + readme: + base-dir: . + input: + - "./README.yaml" + - get_support: true + template: "../../../scripts/docs-collator/component/renderer/templates/components/yml/readme.md" + output: "./README.md" + terraform: + source: ./src + enabled: true + format: "markdown table" + show_providers: false + show_inputs: true + show_outputs: true + sort_by: "name" + hide_empty: false + indent_level: 2 diff --git a/scripts/docs-collator/component/renderer/templates/components/yml/readme.md b/scripts/docs-collator/component/renderer/templates/components/yml/readme.md index fe08e30f1..b6bb4d415 100644 --- a/scripts/docs-collator/component/renderer/templates/components/yml/readme.md +++ b/scripts/docs-collator/component/renderer/templates/components/yml/readme.md @@ -1,8 +1,7 @@ {{- defineDatasource "config" .Env.README_YAML | regexp.Replace ".*" "" -}} -{{- defineDatasource "includes" .Env.README_INCLUDES -}} +{{- defineDatasource "includes" (env.Getenv "README_INCLUDES" | default "./") -}} {{- $deprecated := has (ds "config") "deprecated" -}} {{- $fullModuleName := (ds "config").name -}} -{{- $shortModuleName := ( conv.Default $fullModuleName (conv.Join (coll.GoSlice ($fullModuleName | strings.SplitN "-" 3) 1) "-")) -}} --- title: {{ $fullModuleName }} sidebar_label: {{ $fullModuleName }} @@ -71,9 +70,17 @@ This module is no longer actively maintained {{(ds "config").examples }} {{ end }} +{{ if has (ds "config") "terraform_docs" }} + + +{{ (ds "config").terraform_docs }} + + +{{ end }} + {{ if has (ds "config") "include" }} {{ range $file := (datasource "config").include -}} -{{ (include "includes" $file) }} +{{ (include "includes" ($file)) }} {{- end }} {{- end }} {{- end }} diff --git a/scripts/docs-collator/component/renderer/templates/components/yml/terraform-docs.yml b/scripts/docs-collator/component/renderer/templates/components/yml/terraform-docs.yml index 50b752c14..8a6ef6658 100644 --- a/scripts/docs-collator/component/renderer/templates/components/yml/terraform-docs.yml +++ b/scripts/docs-collator/component/renderer/templates/components/yml/terraform-docs.yml @@ -204,10 +204,6 @@ output-values: output: file: ../README.md mode: inject - template: |- - - {{ .Content }} - settings: anchor: true diff --git a/scripts/docs-collator/component/renderer/templates/make/Makefile b/scripts/docs-collator/component/renderer/templates/make/Makefile deleted file mode 100644 index b25677208..000000000 --- a/scripts/docs-collator/component/renderer/templates/make/Makefile +++ /dev/null @@ -1,3 +0,0 @@ -SHELL := /bin/bash - --include $(shell curl -sSL -o .build-harness "https://cloudposse.tools/build-harness"; echo .build-harness) diff --git a/scripts/docs-collator/component/renderer/yml.py b/scripts/docs-collator/component/renderer/yml.py index f5d4d8938..82f3760ff 100644 --- a/scripts/docs-collator/component/renderer/yml.py +++ b/scripts/docs-collator/component/renderer/yml.py @@ -9,7 +9,7 @@ SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__)) README_YAML = "README.yaml" README_MD = "README.md" - +ATMOS_YAML = "atmos.yaml" IMAGES_DIR = "images" MODULES_README_TEMPLATE = "readme.md" @@ -40,29 +40,28 @@ def __render_readme(self, module_docs_dir): readme_yaml_file = os.path.join(self.component.dir, README_YAML) readme_md_file = os.path.join(self.component.dir, README_MD) - readme_tmpl_file = os.path.join(self.templates_dir, MODULES_README_TEMPLATE) + atmos_yaml_file = os.path.join(self.templates_dir, ATMOS_YAML) io.create_dirs(module_docs_dir) # Run the make readme command in the module directory to compile README.md logging.debug(f"Rendering README.md for: {self.component.dir}") - logging.debug(f"make readme") - logging.debug(f"README_TEMPLATE_FILE: {readme_tmpl_file}") + logging.debug(f"atmos docs generate readme --config {atmos_yaml_file}") + logging.debug(f"ATMOS_YAML_FILE: {atmos_yaml_file}") logging.debug(f"README_FILE: {readme_md_file}") logging.debug(f"README_YAML: {readme_yaml_file}") - logging.debug(f"README_TEMPLATE_YAML: {readme_yaml_file}") - logging.debug(f"README_INCLUDES: {self.component.dir}") + logging.debug(f"README_MD: {readme_md_file}") + logging.debug(f"COMPONENT_DIR: {self.component.dir}") response = subprocess.run( [ - "make", + "atmos", + "--config", + f"{atmos_yaml_file}", + "docs", + "generate", "readme", - f"README_TEMPLATE_FILE={os.path.abspath(readme_tmpl_file)}", - f"README_FILE={os.path.abspath(readme_md_file)}", - f"README_YAML={os.path.abspath(readme_yaml_file)}", - f"README_TEMPLATE_YAML={os.path.abspath(readme_yaml_file)}", - f"README_INCLUDES={os.path.abspath(self.component.dir)}/", ], capture_output=True, - cwd=os.path.join(SCRIPT_DIR, "templates", "make"), + cwd=self.component.dir, ) if response.returncode != 0: @@ -73,7 +72,7 @@ def __render_readme(self, module_docs_dir): # Re-render terraform docs with this repo's terraform-docs template for modules. # This replaces docs/terraform.md for the given module in place - logging.debug(f"Rendering terraform docs for: {self.component.dir}") + # logging.debug(f"Rendering terraform docs for: {self.component.dir}") rendering.render_terraform_docs( self.component.terraform_dir, os.path.join(self.templates_dir, "terraform-docs.yml") ) diff --git a/scripts/docs-collator/templates/github-actions/atmos.yaml b/scripts/docs-collator/templates/github-actions/atmos.yaml new file mode 100644 index 000000000..0fde263b2 --- /dev/null +++ b/scripts/docs-collator/templates/github-actions/atmos.yaml @@ -0,0 +1,20 @@ +docs: + generate: + readme: + base-dir: . + input: + - "./action.yml" + - "./README.yaml" + - get_support: true + template: "../../../scripts/docs-collator/templates/github-actions/readme.md" + output: "./README.md" + terraform: + source: . + enabled: false + format: "markdown table" + show_providers: false + show_inputs: true + show_outputs: true + sort_by: "name" + hide_empty: false + indent_level: 2 diff --git a/scripts/docs-collator/templates/github-actions/readme.md b/scripts/docs-collator/templates/github-actions/readme.md index a116ec1f7..2ab4c25dc 100644 --- a/scripts/docs-collator/templates/github-actions/readme.md +++ b/scripts/docs-collator/templates/github-actions/readme.md @@ -1,8 +1,11 @@ {{- defineDatasource "config" .Env.README_YAML -}} -{{- defineDatasource "includes" (env.Getenv "README_INCLUDES") -}} +{{- defineDatasource "includes" (env.Getenv "README_INCLUDES" | default "./") -}} {{- $deprecated := has (ds "config") "deprecated" -}} {{- $fullName := (ds "config").name -}} -{{- $shortName := (index ($fullName | strings.SplitN "-" 3) 2) -}} +{{- $shortName := (index ((ds "config").github_repo | strings.SplitN "-" 3) 2) -}} +{{/* Inspired https://github.com/Dirrk/action-docs/blob/master/src/default_template.tpl */}} +{{- define "escape_chars" }}{{ . | strings.ReplaceAll "_" "\\_" | strings.ReplaceAll "|" "\\|" | strings.ReplaceAll "*" "\\*" }}{{- end }} +{{- define "sanitize_string" }}{{ . | strings.ReplaceAll "\n\n" "

" | strings.ReplaceAll " \n" "
" | strings.ReplaceAll "\n" "
" | tmpl.Exec "escape_chars" }}{{ end -}} --- title: {{ $shortName }} sidebar_label: {{ $shortName }} @@ -73,9 +76,32 @@ custom_edit_url: https://github.com/cloudposse/{{ $fullName }}/edit/main/README. {{(ds "config").examples }} {{ end }} +{{- $action := (datasource "config") -}} +{{ if has $action "inputs" }} +## Inputs + +| Name | Description | Default | Required | +|------|-------------|---------|----------| +{{- range $key, $input := $action.inputs }} +| {{ tmpl.Exec "escape_chars" $key }} | {{ if (has $input "description") }}{{ tmpl.Exec "sanitize_string" $input.description }}{{ else }}{{ tmpl.Exec "escape_chars" $key }}{{ end }} | {{ if (has $input "default") }}{{ tmpl.Exec "sanitize_string" $input.default }}{{ else }}N/A{{ end }} | {{ if (has $input "required") }}{{ $input.required }}{{ else }}false{{ end }} | +{{- end }} + +{{- end }} + +{{ if has $action "outputs" }} +## Outputs + +| Name | Description | +|------|-------------| +{{- range $key, $output := $action.outputs }} +| {{ tmpl.Exec "escape_chars" $key }} | {{ if (has $output "description") }}{{ tmpl.Exec "sanitize_string" $output.description }}{{ else }}{{ tmpl.Exec "escape_chars" $key }}{{ end }} | +{{- end }} + +{{- end }} + {{ if has (ds "config") "include" }} {{ range $file := (datasource "config").include -}} -{{ (include "includes" (printf "%s/%s" $fullName $file)) }} +{{ (include "includes" ($file)) }} {{- end }} {{- end }} {{- end }} diff --git a/scripts/docs-collator/templates/modules/atmos.yaml b/scripts/docs-collator/templates/modules/atmos.yaml new file mode 100644 index 000000000..8af7fcd38 --- /dev/null +++ b/scripts/docs-collator/templates/modules/atmos.yaml @@ -0,0 +1,36 @@ +docs: + generate: + readme: + base-dir: . + input: + - "./README.yaml" + - get_support: true + template: "../../../scripts/docs-collator/templates/modules/readme.md" + output: "./README.md" + terraform: + source: . + enabled: true + format: "markdown table" + show_providers: false + show_inputs: true + show_outputs: true + sort_by: "name" + hide_empty: false + indent_level: 2 + + submodule-readme: + base-dir: . + input: + - "./README.yaml" + template: "../../../../../scripts/docs-collator/templates/modules/submodule.readme.yaml.md" + output: "./README.md" + terraform: + source: . + enabled: true + format: "markdown table" + show_providers: false + show_inputs: true + show_outputs: true + sort_by: "name" + hide_empty: false + indent_level: 2 diff --git a/scripts/docs-collator/templates/modules/readme.md b/scripts/docs-collator/templates/modules/readme.md index 2e7cb81a0..0ddcf0c1d 100644 --- a/scripts/docs-collator/templates/modules/readme.md +++ b/scripts/docs-collator/templates/modules/readme.md @@ -1,5 +1,5 @@ {{- defineDatasource "config" .Env.README_YAML | regexp.Replace ".*" "" -}} -{{- defineDatasource "includes" .Env.README_INCLUDES | regexp.Replace ".*" "" -}} +{{- defineDatasource "includes" (env.Getenv "README_INCLUDES" | default "./") -}} {{- $deprecated := has (ds "config") "deprecated" -}} {{- $fullModuleName := (ds "config").name -}} {{- $shortModuleName := (index ($fullModuleName | strings.SplitN "-" 3) 2) -}} @@ -73,9 +73,17 @@ custom_edit_url: https://github.com/cloudposse/{{ $fullModuleName }}/edit/main/R {{(ds "config").examples }} {{ end }} +{{ if has (ds "config") "terraform_docs" }} + + +{{ (ds "config").terraform_docs }} + + +{{ end }} + {{ if has (ds "config") "include" }} {{ range $file := (datasource "config").include -}} -{{ (include "includes" (printf "%s/%s" $fullModuleName $file)) }} +{{ (include "includes" ($file)) }} {{- end }} {{- end }} {{- end }} diff --git a/scripts/docs-collator/templates/modules/submodule.readme.yaml.md b/scripts/docs-collator/templates/modules/submodule.readme.yaml.md new file mode 100644 index 000000000..0a24c387c --- /dev/null +++ b/scripts/docs-collator/templates/modules/submodule.readme.yaml.md @@ -0,0 +1,89 @@ +{{- defineDatasource "config" .Env.README_YAML | regexp.Replace ".*" "" -}} +{{- defineDatasource "includes" (env.Getenv "README_INCLUDES" | default "./") -}} +{{- $deprecated := has (ds "config") "deprecated" -}} +{{- $fullModuleName := (ds "config").name -}} +{{- $shortModuleName := $fullModuleName -}} +--- +title: {{ $shortModuleName }} +sidebar_label: {{ $shortModuleName }} +sidebar_class_name: command +{{- if has (ds "config") "description" }} +description: |- +{{ (ds "config").description | strings.Indent 2 }} +{{- end }} +{{- if has (ds "config") "tags" }} +tags: +{{ (ds "config").tags | data.ToYAML | strings.Indent 2 -}} +{{- end }} +custom_edit_url: https://github.com/cloudposse/{{ $fullModuleName }}/edit/main/README.md +--- + +# Module: `{{ $shortModuleName }}` + +{{- if $deprecated }} +## Deprecated + +{{ if has (ds "config").deprecated "notice" }} + {{- (ds "config").deprecated.notice }} +{{- else }} + This module is no longer actively maintained +{{- end }} + +{{ if has (ds "config") "description" }} +### Historical Description + +{{(ds "config").description }} +{{- end }} +{{- else }} +{{- if has (ds "config") "description" }} +{{ (ds "config").description }} + +{{- end }} +{{- end }} + +{{ if has (ds "config") "screenshots" }} +## Screenshots + +{{ range $screenshot := (ds "config").screenshots }} +{{ printf "![%s](%s)\n*%s*" $screenshot.name $screenshot.url $screenshot.description }}{{ end }} +{{- end }} + +{{ if has (ds "config") "introduction" }} +## Introduction + +{{ (ds "config").introduction }} +{{ end }} + +{{ if has (ds "config") "usage" }} +## Usage + +{{ (ds "config").usage -}} +{{ end }} + +{{ if not $deprecated -}} +{{ if has (ds "config") "quickstart" -}} +## Quick Start + +{{ (ds "config").quickstart -}} +{{ end }} + +{{ if has (ds "config") "examples" }} +## Examples + +{{(ds "config").examples }} +{{ end }} + +{{ if has (ds "config") "terraform_docs" }} + + +{{ (ds "config").terraform_docs }} + + +{{ end }} + +{{ if has (ds "config") "include" }} +{{ range $file := (datasource "config").include -}} +{{ (include "includes" ($file)) }} +{{- end }} +{{- end }} +{{- end }} diff --git a/scripts/docs-collator/templates/modules/terraform-docs.yml b/scripts/docs-collator/templates/modules/terraform-docs.yml index 8070f1fc3..008e1c3b5 100644 --- a/scripts/docs-collator/templates/modules/terraform-docs.yml +++ b/scripts/docs-collator/templates/modules/terraform-docs.yml @@ -202,8 +202,8 @@ output-values: from: '' output: - file: docs/terraform.md - mode: replace + file: README.md + mode: inject #output: # file: README.md # mode: inject diff --git a/scripts/render-docs-for-components.sh b/scripts/render-docs-for-components.sh index 9d268e89c..4d4096306 100755 --- a/scripts/render-docs-for-components.sh +++ b/scripts/render-docs-for-components.sh @@ -11,4 +11,5 @@ DOWNLOAD_TMP_DIR="${DOWNLOAD_TMP_DIR:-tmp/components}" python scripts/docs-collator/render_docs_for_components.py \ --download-dir "${DOWNLOAD_TMP_DIR}" \ --output-dir "${RENDERED_DOCS_DIR}" \ - --excludes "vpc" + --excludes "vpc,template,mixins" \ + --log-level DEBUG diff --git a/scripts/render-docs-for-github-actions.sh b/scripts/render-docs-for-github-actions.sh index af3554552..08ae404a0 100755 --- a/scripts/render-docs-for-github-actions.sh +++ b/scripts/render-docs-for-github-actions.sh @@ -15,4 +15,4 @@ DOWNLOAD_TMP_DIR="${DOWNLOAD_TMP_DIR:-tmp/github-actions}" python scripts/docs-collator/render_docs_for_github_actions.py \ --download-dir "${DOWNLOAD_TMP_DIR}" \ --output-dir "${RENDERED_DOCS_DIR}" \ - --excludes 'github-action-ci-terraform' + --excludes 'github-action-ci-terraform,github-action-atmos-dependencies-test'