feat(gh-actions): automates docs update based on README changes

.github/workflows/doc_update.yml

@@ -0,0 +1,123 @@
+name: Update sections in docs based on README
+
+on:
+  pull_request:
+    paths:
+      - README.md
+
+jobs:
+  doc_update:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 1
+      - name: Set GitHub user
+        env:
+          GIT_USER: ${{secrets.GIT_USER}}
+          GIT_EMAIL: ${{secrets.GIT_EMAIL}}
+        run: |
+          git config --local user.name "${GIT_USER}"
+          git config --local user.email "${GIT_EMAIL}"
+      - name: Checkout PR branch
+        id: checkout
+        uses: actions/github-script@v5
+        with:
+          github-token: ${{secrets.GH_RELEASE_TOKEN}}
+          script: |
+            const pr = await github.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number
+            });
+
+            const prHead = pr.data.head.sha;
+            core.setOutput("pr_head", prHead);
+            core.setOutput("pr_title", pr.data.title.trim());
+
+            const result = await github.request("POST /repos/:owner/:repo/statuses/:sha", {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: prHead,
+              context: 'docs / generate',
+              state: 'pending',
+            });
+
+            const { spawnSync } = require("child_process")
+            const { status, stderr } = spawnSync(`git fetch origin pull/${pr.data.number}/head:${pr.data.head.ref} && git checkout ${pr.data.head.ref} && git push --set-upstream origin ${pr.data.head.ref}`, {shell: true});
+
+            if (status != 0) {
+              core.exportVariable("STATUS", JSON.stringify({ sha: prHead,
+                context: 'docs / generate',
+                state: 'error',
+                description: 'Failed checking out PR branch',
+                details: stderr.toString(),
+              }));
+              core.setFailed('Failed checking out PR branch');
+            }
+      - name: Generate doc updates
+        if: success()
+        uses: actions/github-script@v5
+        with:
+          github-token: ${{secrets.GH_RELEASE_TOKEN}}
+          script: |
+            const version = "${{ steps.validation.outputs.version }}";
+            const prHead = "${{ steps.checkout.outputs.pr_head }}";
+
+            const { spawnSync } = require("child_process");
+            const { status, stderr } = spawnSync(`./scripts/dev/update-docs.sh`, {shell: true});
+
+            if (status != 0) {
+                core.exportVariable("STATUS", JSON.stringify({ sha: prHead,
+                  context: 'docs / generate',
+                  state: 'failure',
+                  description: 'Failed generating docs',
+                  details: stderr.toString(),
+                }));
+                core.setFailed('Failed generating docs');
+            } else {
+              const pushCmd = `git add . && git commit -m"docs: updates docs based on README changes" -m"/skip-e2e" -m"/skip-build" && git push && git rev-parse --short HEAD`;
+              const { status, stderr, stdout } = spawnSync(pushCmd, {shell: true});
+              if (status != 0) {
+                  core.exportVariable("STATUS", JSON.stringify({ sha: prHead,
+                    context: 'docs / generate',
+                    state: 'error',
+                    description: 'Failed committing docs update',
+                    details: stderr.toString(),
+                  }));
+                  core.setFailed('Failed committing docs update');
+              } else {
+                const { status, stderr, stdout } = spawnSync('echo -n $(git rev-parse HEAD)', {shell: true});
+                core.exportVariable("STATUS", JSON.stringify({ sha: stdout.toString(),
+                  context: 'docs / generate',
+                  state: 'success',
+                  description: 'Docs update generated',
+                }));
+              }
+            }
+      - name: Publish job status and comment with details
+        if: always()
+        uses: actions/github-script@v5
+        with:
+          github-token: ${{secrets.GH_RELEASE_TOKEN}}
+          script: |
+            const status = ${{env.STATUS}};
+
+            const result = await github.request("POST /repos/:owner/:repo/statuses/:sha", {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: status.sha,
+              context: status.context,
+              state: status.state,
+              description: status.description,
+              target_url: "https://github.com/${{github.repository}}/actions/runs/${{github.run_id}}",
+            });
+
+            if (status.details) {
+              github.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: `#### ⚠ ${status.description}\n\n${status.details}`,
+              });
+            }

Makefile

@@ -380,7 +380,7 @@ bundle: $(PROJECT_DIR)/bin/operator-sdk $(PROJECT_DIR)/bin/kustomize $(DIST_DIR)
 	sed -i 's/COPY bundle\//COPY /g' build/bundle.Containerfile
 	sed -i 's/containerImage: controller:latest/containerImage: $(IKE_CONTAINER_REGISTRY)\/$(IKE_CONTAINER_REPOSITORY)\/$(IKE_IMAGE_NAME):$(IKE_IMAGE_TAG)/' $(PROJECT_DIR)/$(CSV_FILE)
 	sed -i 's/createdAt: "1970-01-01 00:00:0"/createdAt: $(shell date -u +%Y-%m-%dT%H:%M:%SZ)/' $(PROJECT_DIR)/$(CSV_FILE)
-	cat $(PROJECT_DIR)/README.md | awk '/tag::description/{flag=1;next}/end::description/{flag=0}flag' > $(PROJECT_DIR)/$(DESC_FILE)
+	cat $(PROJECT_DIR)/README.md | awk '/start::description/{flag=1;next}/end::description/{flag=0}flag' > $(PROJECT_DIR)/$(DESC_FILE)
 	sed -i 's/^/    /g' $(PROJECT_DIR)/$(DESC_FILE) # to make YAML happy we have to indent each line for the description field
 	sed -i -e '/insert::description-from-readme/{r $(PROJECT_DIR)/$(DESC_FILE)' -e 'd}' $(PROJECT_DIR)/$(CSV_FILE)
 	rm $(DESC_FILE)

README.md

@@ -3,33 +3,35 @@
 ![CircleCI](https://circleci.com/gh/maistra/istio-workspace.svg?style=svg)
 
 # Istio Workspace
-
-<!-- tag::description[] -->
+<!-- Following tag is extracted to operator description when building a bundle using `make bundle` -->
+<!-- start::description[] -->
+<!-- start::overview[] -->
 Istio Workspace enables developers to:
 
- * run one or more services locally during development but make it appear like it would be developed in the actual cluster
-   * this way you can use your favourite development tools
-   * have instant feedback loop
-   * don't make your machine overheating trying to run the whole cluster locally
- * safely preview incoming changes in pull requests without affecting regular users 
- * have confidence in testing or troubleshooting your services directly in the cluster
+* run one or more services locally during development but make it appear like it would be developed in the actual cluster
+  * this way you can use your favourite development tools
+  * have instant feedback loop
+  * don't make your machine overheating trying to run the whole cluster locally
+* safely preview incoming changes in pull requests without affecting regular users
+* have confidence in testing or troubleshooting your services directly in the cluster
 
 Istio Workspace supports testing on multi-user environment in an unobtrusive way.
 It doesn’t really matter if it is QE cluster or actual production. We give you confidence that your changes won’t blow up the cluster, and your users won’t even notice a glitch.
 
-You will need [Kubernetes](https://k8s.io) or [Openshift](https://openshift.com) cluster with  [Istio](https://istio.io/) installed. 
+You will need [Kubernetes](https://k8s.io) or [Openshift](https://openshift.com) cluster with [Istio](https://istio.io/) installed.
 
 You can read more about our vision on [Red Hat Developer’s blog](https://developers.redhat.com/blog/2020/07/14/developing-and-testing-on-production-with-kubernetes-and-istio-workspace/) or ...
 
+<!-- end::overview[] -->
 ## See it in action!
 
 [![https://youtu.be/XTNVadUzMCc](https://img.youtube.com/vi/XTNVadUzMCc/hqdefault.jpg)](https://youtu.be/XTNVadUzMCc)
 
-Watch demo: ["How to develop on production: An introduction to Istio-Workspaces"](https://youtu.be/XTNVadUzMCc).
+Watch the demo: ["How to develop on production: An introduction to Istio-Workspaces"](https://youtu.be/XTNVadUzMCc).
 
 ## Documentation
 
-More details can be found on our [documentation page](https://istio-workspace-docs.netlify.com/).
+Head over to our [documentation page](https://istio-workspace-docs.netlify.com/) to learn the details!
 
 <!-- end::description[] -->
 
@@ -41,9 +43,7 @@ Get latest `ike` binary through simple download script:
 
     curl -sL http://git.io/get-ike | bash
 
-> **Tip**
->
-> You can also specify the version and directory before downloading `curl -sL http://git.io/get-ike | bash -s -- --version=v0.0.1 --dir=/usr/bin`
+> TIP: You can also specify the version and directory before downloading `curl -sL http://git.io/get-ike | bash -s -- --version=v0.4.0 --dir=/usr/bin`
 
     get - downloads ike binary matching your operating system
 
@@ -57,45 +57,29 @@ Get latest `ike` binary through simple download script:
 
 If you’re using Openshift you can install the `istio-workspace operator` via the Operator Hub in the web console.
 
-If you’re on vanilla Kubernetes you can install it by installing the `Operator Lifecycle Managment` using the [Operator SDK](https://sdk.operatorframework.io/docs/installation/):
-
-    operator-sdk install
-    operator-sdk run bundle quay.io/maistra/istio-workspace-operator-bundle:latest
-
-And you are all set!
+If you’re on vanilla Kubernetes follow the instructions on [OperatorHub.io](https://operatorhub.io/operator/istio-workspace-operator) to see how you can install operators.
 
 ## Development Setup
 
+<!-- start::dev-setup[] -->
 Assuming that you have all the [Golang prerequisites](https://golang.org/doc/install) in place, clone the repository first:
 
     $ git clone https://github.com/maistra/istio-workspace $GOPATH/src/github.com/maistra/istio-workspace
 
-We rely on following tools:
-
--   [`dep`](https://golang.github.io/dep/) for dependency management
-
--   [`golang-ci`](https://github.com/golangci/golangci-lint) linter
-
--   [`ginkgo`](https://github.com/onsi/ginkgo) for testing
-
--   [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports) for formatting
-
--   [`operator-sdk`](https://github.com/operator-framework/operator-sdk) for code generation
-
-but from now on you are ready to hack - invoking `make` will check if those binaries are available and install if there are some missing.
+From now on you are ready to hack - invoking `make` will check if required binaries are available and install if there are some missing.
 
 Run `make help` to see what targets are available, but you will use `make` most often.
 
-> **Note**
->
-> Have a look how [Go Version Manager](https://github.com/moovweb/gvm) can help you simplifying configuration
+> NOTE: Have a look how [Go Version Manager](https://github.com/moovweb/gvm) can help you simplifying configuration
 > and management of different versions of Go.
 
 ### Coding style
 
 We follow standard Go coding conventions which we ensure using `goimports` during the build.
 
-In addition, we provide `.editorconfig` file which is supported by [majority of the IDEs](https://editorconfig.org/#download).
+In addition, we provide `.editorconfig` file which is supported by [majority of the IDEs](https://editorconfig.org/#download). That should help avoid coding style mismatches.
+
+<!-- end::dev-setup[] -->
 
 ## License
 

docs/modules/ROOT/pages/contribution_guide.adoc

@@ -27,31 +27,28 @@ If you don't know where to start - have a look at https://github.com/Maistra/ist
 
 === Setup
 
-Assuming that you have all the link:https://golang.org/doc/install[Golang prerequisites] in place, clone the repository first:
+// start:dev-setup
+Assuming that you have all the https://golang.org/doc/install[Golang prerequisites] in place, clone the repository first:
 
-[source,bash]
-----
+....
 $ git clone https://github.com/maistra/istio-workspace $GOPATH/src/github.com/maistra/istio-workspace
-----
+....
 
-TIP: Have a look how link:https://github.com/moovweb/gvm[Go Version Manager] can help you simplify configuration
-and management of different versions of Go.
-
-We rely on following tools:
+From now on you are ready to hack - invoking `make` will check if required binaries are available and install if there are some missing.
 
-* https://golang.github.io/dep/[`dep`] for dependency management,
-* https://github.com/golangci/golangci-lint[`golang-ci`] linter,
-* https://github.com/onsi/ginkgo[`ginkgo`] for testing,
-* https://godoc.org/golang.org/x/tools/cmd/goimports[`goimports`] for formatting,
-* https://github.com/operator-framework/operator-sdk[`operator-sdk`] for code generation.
+Run `make help` to see what targets are available, but you will use `make` most often.
 
-Build process takes care of installing those binaries on your behalf. You can also run `make tools` to install them.
+____
+NOTE: Have a look how https://github.com/moovweb/gvm[Go Version Manager] can help you simplifying configuration
+and management of different versions of Go.
+____
 
-=== Coding
+== Coding style
 
-From now on you are ready to hack. Open your favorite IDE and start right away! To build and test the code simply run `make`.
+We follow standard Go coding conventions which we ensure using `goimports` during the build.
 
-TIP: Run `make help` to see what other targets are available.
+In addition, we provide `.editorconfig` file which is supported by https://editorconfig.org/#download[majority of the IDEs]. That should help avoid coding style mismatches.
+// end:dev-setup
 
 === Testing
 

docs/modules/ROOT/pages/index.adoc

@@ -4,9 +4,23 @@ Do you have confidence that your Test and Stage environments reflect reality? Ar
 
 It's been always hard to test new functionality before it reaches production. Even more so, with the shift from a monolith to microservices and increasing scale. Can you still spin up the entire solution on your laptop to debug and test a suspicious piece of code? Testing on production is no longer a meme. It’s reality and a necessity.
 
-This project works with https://istio.io/[Istio] and https://k8s.io[Kubernetes] or https://openshift.com[Openshift] to give you confidence that your changes won't blow up production cluster, and your users won’t even notice a glitch.
+// start:overview
+Istio Workspace enables developers to:
 
-You can read more about our vision on https://developers.redhat.com/blog/2020/07/14/developing-and-testing-on-production-with-kubernetes-and-istio-workspace/[Red Hat Developer's blog] or ...
+* run one or more services locally during development but make it appear like it would be developed in the actual cluster
+** this way you can use your favourite development tools
+** have instant feedback loop
+** don't make your machine overheating trying to run the whole cluster locally
+* safely preview incoming changes in pull requests without affecting regular users
+* have confidence in testing or troubleshooting your services directly in the cluster
+
+Istio Workspace supports testing on multi-user environment in an unobtrusive way.
+It doesn’t really matter if it is QE cluster or actual production. We give you confidence that your changes won’t blow up the cluster, and your users won’t even notice a glitch.
+
+You will need https://k8s.io[Kubernetes] or https://openshift.com[Openshift] cluster with https://istio.io/[Istio] installed.
+
+You can read more about our vision on https://developers.redhat.com/blog/2020/07/14/developing-and-testing-on-production-with-kubernetes-and-istio-workspace/[Red Hat Developer’s blog] or ...
+// end:overview
 
 == See it in action!
 

scripts/dev/update-docs.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if ! command -v pandoc &> /dev/null
+then
+    echo "pandoc could not be found. installing..."
+    PANDOC_VERSION=2.11.4
+    cd /tmp
+    wget "https://github.com/jgm/pandoc/releases/download/${PANDOC_VERSION}/pandoc-${PANDOC_VERSION}-linux-amd64.tar.gz" -O "pandoc.tar.gz"
+    tar xzfv pandoc.tar.gz
+    sudo mv "${PWD}"/pandoc-${PANDOC_VERSION}/bin/pandoc /usr/local/bin/
+    cd -
+fi
+
+function update_sections() {
+  name="$1"
+  path="$2"
+  awk '/start::'"${name}"'/{flag=1;next}/end::'"${name}"'/{flag=0}flag' README.md | pandoc --wrap=preserve --from gfm --to asciidoc > /tmp/"${name}"
+  sed -i -ne '/start:'"${name}"'/{p;r /tmp/'"${name}"'' -e ':a;n;/end:'"${name}"'/!ba};p' "${path}"
+}
+
+update_sections "overview" "docs/modules/ROOT/pages/index.adoc"
+update_sections "dev-setup" "docs/modules/ROOT/pages/contribution_guide.adoc"