Docs collate for GitHub Actions (#556)

Documents collate for GitHub Actions

Author: zdmytriv

.github/workflows/website-deploy-preview.yml

@@ -77,6 +77,12 @@ jobs:
         run: |
           ./scripts/render-docs-for-modules.sh
 
+      - name: "Render Documentation for GitHub Actions"
+        env:
+          PUBLIC_REPO_ACCESS_TOKEN: ${{ secrets.PUBLIC_REPO_ACCESS_TOKEN }}
+        run: |
+          ./scripts/render-docs-for-github-actions.sh
+
       - name: Install Dependencies and Build Website
         env:
           GOOGLE_TAG_MANAGER: GTM-ABCD123

.github/workflows/website-deploy-release.yml

@@ -64,16 +64,22 @@ jobs:
           make init
           pip install -r scripts/docs-collator/requirements.txt
 
-      - name: "Render docs for components"
+      - name: "Render Documentation for Terraform Components"
         run: |
           ./scripts/render-docs-for-components.sh
 
-      - name: "Render docs for modules"
+      - name: "Render Documentation for Terraform Modules"
         env:
           PUBLIC_REPO_ACCESS_TOKEN: ${{ secrets.PUBLIC_REPO_ACCESS_TOKEN }}
         run: |
           ./scripts/render-docs-for-modules.sh
 
+      - name: "Render Documentation for GitHub Actions"
+        env:
+          PUBLIC_REPO_ACCESS_TOKEN: ${{ secrets.PUBLIC_REPO_ACCESS_TOKEN }}
+        run: |
+          ./scripts/render-docs-for-github-actions.sh
+
       - name: Install Dependencies and Build Website
         env:
           GOOGLE_TAG_MANAGER: ${{ vars.GOOGLE_TAG_MANAGER }}

.gitignore

@@ -57,3 +57,4 @@ algolia.index.json
 **/__pycache__/
 content/components/catalog/aws/**
 content/modules/catalog/**
+content/github-actions/catalog/actions/**

content/github-actions/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "GitHub Actions",
+  "position": 0,
+  "link": {
+    "type": "doc",
+    "id": "index"
+  }
+}

content/github-actions/catalog/actions/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "actions",
+  "collapsible": true,
+  "collapsed": false,
+  "className": "command",
+  "link": {
+    "type": "generated-index",
+    "title": "GitHub Actions"
+  }
+}

content/github-actions/index.md

@@ -0,0 +1,12 @@
+---
+title: GitHub Actions
+sidebar_label: Overview of GitHub Actions
+description: GitHub Actions
+sidebar_position: 0
+---
+
+This is a collection of reusable GitHub Actions.
+
+## Introduction
+
+In this library you'll find real-world examples of how we've implemented reusable GitHub Actions to solve common CI/CD challenges.

docusaurus.config.js

@@ -45,6 +45,15 @@ const config = {
         sidebarPath: require.resolve('./sidebars-modules.js')
       },
     ],
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        id: 'github_actions',
+        path: 'content/github-actions',
+        routeBasePath: 'github-actions/',
+        sidebarPath: require.resolve('./sidebars-github-actions.js')
+      },
+    ],
     [
       "@docusaurus/plugin-google-gtag",
       {
@@ -120,6 +129,11 @@ const config = {
               position: 'left',
               label: 'Modules',
           },
+          {
+              to: '/github-actions/',
+              position: 'left',
+              label: 'GitHub Actions',
+          },
           {
             type: 'dropdown',
             label: 'Community',

scripts/README.md

@@ -1,8 +1,9 @@
 # Usage for docs-collator
 
-Document collation supports 2 types of projects:
+Document collation supports 3 types of projects:
 - components - `cloudposse/terraform-aws-component` - components from single repo `cloudposse/terraform-aws-component` under `modules/` dir 
-- modules - `cloudposse/terraform-*` - for all public (non archived) repos except `cloudposse/terraform-aws-component` that are prefixed with `terraform-`
+- modules - `cloudposse/terraform-*` - for all public (non-archived) repos except `cloudposse/terraform-aws-component` that are prefixed with `terraform-`
+- github actions - `cloudposse/github-action-*` - for all public (non-archived) repos that are prefixed with `github-action-`
 
 Python is used for both tools so make sure to install python requirements.
 
@@ -12,13 +13,13 @@ Python is used for both tools so make sure to install python requirements.
 pip install -r scripts/docs-collator/requirements.txt
 ```
 
-### Render Documentation for Components
+### Render Documentation for Terraform Components
 
 ```bash
 ./scripts/render-docs-for-components.sh
 ```
 
-### Render Documentation for Modules
+### Render Documentation for Terraform Modules
 
 Since this script uses the Github API, the GitHub access token should be set as the `PUBLIC_REPO_ACCESS_TOKEN ` environment variable.
 
@@ -27,3 +28,13 @@ export PUBLIC_REPO_ACCESS_TOKEN=<github-api-token>
 
 ./scripts/render-docs-for-modules.sh
 ```
+
+### Render Documentation for GitHub Actions
+
+This script also uses GitHub API, so the GitHub access token should be set as the `PUBLIC_REPO_ACCESS_TOKEN ` environment variable.
+
+```bash
+export PUBLIC_REPO_ACCESS_TOKEN=<github-api-token>
+
+./scripts/render-docs-for-github-actions.sh
+```

scripts/docs-collator/AbstractFetcher.py

@@ -0,0 +1,29 @@
+import os
+
+DOCS_DIR = 'docs'
+TARGETS_MD = 'targets.md'
+README_YAML = 'README.yaml'
+
+
+class MissingReadmeYamlException(Exception):
+    def __init__(self):
+        self.message = "README.yaml is missing"
+        super().__init__(self.message)
+
+
+class AbstractFetcher:
+    def __init__(self, github_provider, download_dir):
+        self.download_dir = download_dir
+        self.github_provider = github_provider
+
+    def _fetch_readme_yaml(self, repo, module_download_dir):
+        self.github_provider.fetch_file(repo, README_YAML, module_download_dir)
+
+    def _fetch_docs(self, repo, module_download_dir):
+        remote_files = self.github_provider.list_repo_dir(repo, DOCS_DIR)
+
+        for remote_file in remote_files:
+            if os.path.basename(remote_file) == TARGETS_MD:  # skip targets.md
+                continue
+
+            self.github_provider.fetch_file(repo, remote_file, module_download_dir)

scripts/docs-collator/AbstractRenderer.py

@@ -0,0 +1,44 @@
+import logging
+import os
+
+from utils import io
+from utils import rendering
+
+README_YAML = 'README.yaml'
+DOCS_DIR = 'docs'
+
+
+class TerraformDocsRenderingError(Exception):
+    def __init__(self, message):
+        self.message = message
+        super().__init__(f"Failed to render README.md. {message}")
+
+
+class AbstractRenderer:
+    def _pre_rendering_fixes(self, repo, module_download_dir):
+        readme_yaml_file = os.path.join(module_download_dir, README_YAML)
+        content = io.read_file_to_string(readme_yaml_file)
+        content = rendering.remove_targets_md(content)
+        content = rendering.rename_name(repo, content)
+        io.save_string_to_file(readme_yaml_file, content)
+
+    def _post_rendering_fixes(self, repo, readme_md_file):
+        content = io.read_file_to_string(readme_md_file)
+        content = rendering.fix_self_non_closing_br_tags(content)
+        content = rendering.fix_custom_non_self_closing_tags_in_pre(content)
+        content = rendering.fix_github_edit_url(content, repo)
+        content = rendering.fix_sidebar_label(content, repo)
+        io.save_string_to_file(readme_md_file, content)
+
+    def _copy_extra_resources_for_docs(self, module_download_dir, module_docs_dir):
+        extra_resources_dir = os.path.join(module_download_dir, DOCS_DIR)
+        files = io.get_filenames_in_dir(extra_resources_dir, '*', True)
+
+        for file in files:
+            if os.path.basename(file).lower().endswith('.md') or os.path.isdir(file):
+                continue
+
+            dest_file = os.path.join(module_docs_dir, DOCS_DIR, os.path.relpath(file, extra_resources_dir))
+            io.copy_file(file, dest_file)
+
+            logging.info(f"Copied extra file: {dest_file}")