From 0869aa161a151b68f7f5ab7eda34e7285ff87a04 Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Wed, 10 Feb 2021 19:31:00 +0100
Subject: [PATCH 1/2] docs(TechDocs): Add GitHub Actions CI example with AWS S3

---
 docs/features/techdocs/configuring-ci-cd.md | 81 +++++++++++++++++++--
 1 file changed, 75 insertions(+), 6 deletions(-)

diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md
index 5841a02fa8..660c7ce97f 100644
--- a/docs/features/techdocs/configuring-ci-cd.md
+++ b/docs/features/techdocs/configuring-ci-cd.md
@@ -27,11 +27,15 @@ REPOSITORY_URL='https://github.com/org/repo'
 git clone $REPOSITORY_URL
 cd repo
 
+# Install @techdocs/cli, mkdocs and mkdocs plugins
+npm install -g @techdocs/cli
+pip install mkdocs-techdocs-core==0.*
+
 # Generate
-npx @techdocs/cli generate
+techdocs-cli generate --no-docker
 
 # Publish
-npx @techdocs/cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name>
+techdocs-cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name>
 ```
 
 That's it!
@@ -40,14 +44,16 @@ Take a look at
 [`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the
 complete command reference, details, and options.
 
-## 1. Setup a workflow
+## Steps
+
+### 1. Setup a workflow
 
 The TechDocs workflow should trigger on CI when any changes are made in the
 repository containing the documentation files. You can be specific and configure
 the workflow to be triggered only when files inside the `docs/` directory or
 `mkdocs.yml` are changed.
 
-## 2. Prepare step
+### 2. Prepare step
 
 The first step on the CI is to clone your documentation source repository in a
 working directory. This is almost always the first step in most CI workflows.
@@ -62,7 +68,7 @@ step.
 
 Eventually we are trying to do a `git clone <https://path/to/docs-repository/>`.
 
-## 3. Generate step
+### 3. Generate step
 
 Install [`npx`](https://www.npmjs.com/package/npx) to use it for running
 `techdocs-cli`. Or you can install using `npm install -g @techdocs/cli`.
@@ -78,7 +84,7 @@ npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./
 `PATH_TO_REPO` should be the location in the file path where the prepare step
 above clones the repository.
 
-## 4. Publish step
+### 4. Publish step
 
 Depending on your cloud storage provider (AWS, Google Cloud, or Azure), set the
 necessary authentication environment variables.
@@ -96,3 +102,66 @@ npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <buc
 
 The updated TechDocs site built in this workflow is now ready to be served by
 the TechDocs plugin in your Backstage app.
+
+## Example: GitHub Actions CI and AWS S3
+
+Here is an example workflow using GitHub Actions CI and AWS S3 storage. You can
+use any CI and other cloud storage providers - Google Cloud Storage and Azure
+Blob Storage.
+
+Add a `.github/workflows/techdocs.yml` file in your
+[Software Template(s)](../software-templates/index.md) like this -
+
+```yaml
+name: Publish TechDocs Site
+
+on:
+  push:
+    branches: [main]
+    # You can even set it to run only when TechDocs related files are updated.
+    # paths:
+    #   - "docs/**"
+    #   - "mkdocs.yml"
+
+jobs:
+  publish-techdocs-site:
+    runs-on: ubuntu-latest
+
+    # The following secrets are required in your CI environment for publishing files to AWS S3.
+    # e.g. You can use GitHub Organization secrets to set them for all existing and new repositories.
+    env:
+      TECHDOCS_S3_BUCKET_NAME: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      AWS_REGION: ${{ secrets.AWS_REGION }}
+      ENTITY_NAMESPACE: 'default'
+      ENTITY_KIND: 'Component'
+      # In a Software template, Scaffolder will replace {{cookiecutter.component_id | jsonify}}
+      # with the correct entity name. This is same as metadata.name in the entity's catalog-info.yaml
+      ENTITY_NAME: '{{ cookiecutter.component_id | jsonify }}'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - uses: actions/setup-node@v2
+      - uses: actions/setup-python@v2
+
+      - name: Install techdocs-cli
+        run: sudo npm install -g @techdocs/cli
+
+      - name: Install mkdocs and mkdocs plugins
+        run: python -m pip install mkdocs-techdocs-core==0.*
+
+      - name: Generate docs site
+        run: techdocs-cli generate --no-docker --verbose
+
+      - name: Publish docs site
+        run:
+          techdocs-cli publish --publisher-type awsS3 --storage-name
+          $TECHDOCS_S3_BUCKET_NAME --entity
+          $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME
+```
+
+When the new Software is created, the first GitHub Action workflow will publish
+the TechDocs site, which can be viewed in your Backstage app.

From 7dc1e43c5536573f534c6b1a5e0895955c839e96 Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Thu, 11 Feb 2021 09:28:08 +0100
Subject: [PATCH 2/2] docs(TechDocs): Improvements to the CI example

Signed-off-by: Himanshu Mishra <himanshu@orkohunter.net>
---
 docs/features/techdocs/configuring-ci-cd.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md
index 660c7ce97f..a9844ef528 100644
--- a/docs/features/techdocs/configuring-ci-cd.md
+++ b/docs/features/techdocs/configuring-ci-cd.md
@@ -106,8 +106,8 @@ the TechDocs plugin in your Backstage app.
 ## Example: GitHub Actions CI and AWS S3
 
 Here is an example workflow using GitHub Actions CI and AWS S3 storage. You can
-use any CI and other cloud storage providers - Google Cloud Storage and Azure
-Blob Storage.
+use any CI and any other
+[TechDocs supported cloud storage providers](README.md#platforms-supported).
 
 Add a `.github/workflows/techdocs.yml` file in your
 [Software Template(s)](../software-templates/index.md) like this -
@@ -136,9 +136,10 @@ jobs:
       AWS_REGION: ${{ secrets.AWS_REGION }}
       ENTITY_NAMESPACE: 'default'
       ENTITY_KIND: 'Component'
+      ENTITY_NAME: 'my-doc-entity'
       # In a Software template, Scaffolder will replace {{cookiecutter.component_id | jsonify}}
       # with the correct entity name. This is same as metadata.name in the entity's catalog-info.yaml
-      ENTITY_NAME: '{{ cookiecutter.component_id | jsonify }}'
+      # ENTITY_NAME: '{{ cookiecutter.component_id | jsonify }}'
 
     steps:
       - name: Checkout code
@@ -163,5 +164,6 @@ jobs:
           $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME
 ```
 
-When the new Software is created, the first GitHub Action workflow will publish
-the TechDocs site, which can be viewed in your Backstage app.
+When the new repository is scaffolded or new documentation updates are
+committed, the GitHub Action workflow will publish the TechDocs site, which can
+be viewed in your Backstage app.