From d9de82ee6c24eb8e84f27bdd490dc456316743c3 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Sat, 9 Jan 2021 23:04:22 +0100 Subject: [PATCH 1/6] docs: How to build TechDocs sites on CI/CD workflows --- docs/features/techdocs/architecture.md | 5 +- docs/features/techdocs/configuring-ci-cd.md | 87 +++++++++++++++++++++ microsite/sidebars.json | 1 + 3 files changed, 90 insertions(+), 3 deletions(-) create mode 100644 docs/features/techdocs/configuring-ci-cd.md diff --git a/docs/features/techdocs/architecture.md b/docs/features/techdocs/architecture.md index 7c35fbc943..53149ae4f3 100644 --- a/docs/features/techdocs/architecture.md +++ b/docs/features/techdocs/architecture.md @@ -142,12 +142,11 @@ Status of all the features mentioned above. - Basic setup with techdocs-backend file server as storage. - Basic setup with cloud storage solution. - -**Work in progress 🚧** - - `techdocs-cli` is able to generate docs in CI/CD environment. - `techdocs-cli` is able to publish docs site to any storage. +**Work in progress 🚧** + **Not implemented yet ❌** - `techdocs-backend` integration with Backstage access control management. diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md new file mode 100644 index 0000000000..ec25684a94 --- /dev/null +++ b/docs/features/techdocs/configuring-ci-cd.md @@ -0,0 +1,87 @@ +--- +id: configuring-ci-cd +title: Configuring CI/CD to generate and publish TechDocs sites +description: + Configuring CI/CD to generate and publish TechDocs sites to cloud storage +--- + +In the [Recommended deployment setup](./architecture.md#recommended-deployment), +TechDocs reads the static generated documentation files from a cloud storage +bucket (GCS, AWS S3, etc.). The documentation site is generated on the CI/CD +workflow associated with the repository containing the documentation files. This +document explains the steps needed to generate docs on CI and publish to a cloud +storage using [`techdocs-cli`](https://github.com/backstage/techdocs-cli). + +The steps here target all kinds of CI providers (GitHub actions, Circle CI, +Jenkins, etc.) Specific tools for individual providers will also be made +available here for simplicity (e.g. A GitHub Actions runner, CircleCI orb, etc.) + +A summary of the instructions below looks like this - + +```sh +# Prepare +REPOSITORY_URL='https://github.com/org/repo' +git clone $REPOSITORY_URL + +# Generate +npx techdocs-cli generate --source-dir ./repo --output-dir ./site + +# Publish +npx techdocs-cli publish --directory ./site --publisher-type awsS3 --bucket-name --entity + +# That's it! +``` + +## 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 trigger +the workflow only on changes to files inside the `docs/` directory or +`mkdocs.yml`. + +## 2. Prepare step + +The first step on the CI is to clone the repository in a working directory. This +is almost always the first step in most CI workflows. + +On GitHub actions, you can add a step + +[`- uses: actions@checkout@v2`](https://github.com/actions/checkout). + +On CircleCI, you can add a special +[`checkout`](https://circleci.com/docs/2.0/configuration-reference/#checkout) +step. + +Eventually we are trying to do a `git clone `. + +## 3. Generate step + +Install [`npx`](https://www.npmjs.com/package/npx) to use it for running +`techdocs-cli`. We are going to use the `techdocs-cli generate` command here. + +Take a look at +[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the +complete command reference, details, and options. + +``` +npx techdocs-cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site +``` + +`PATH_TO_REPO` should be the location where the prepare step above clones the +repository. + +## 4. Publish step + +Take a look at +[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the +complete command reference, details, and options. + +Depending on your cloud storage provider (AWS or Google Cloud), set the +necessary authentication environment variables. + +- [Google Cloud authentication](https://cloud.google.com/storage/docs/authentication#libauth) +- [AWS authentication](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html) + +``` +techdocs-cli publish --directory ./site --publisher-type --bucket-name --entity +``` diff --git a/microsite/sidebars.json b/microsite/sidebars.json index f5a433fc84..4822ffe397 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -91,6 +91,7 @@ "features/techdocs/creating-and-publishing", "features/techdocs/configuration", "features/techdocs/using-cloud-storage", + "features/techdocs/configuring-ci-cd", "features/techdocs/how-to-guides", "features/techdocs/troubleshooting", "features/techdocs/faqs" From 0dc2e8a97ebc0a26be25a261a0289e86981d62e1 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Sun, 10 Jan 2021 10:19:45 +0100 Subject: [PATCH 2/6] docs: fix npx command for techdocs-cli --- docs/features/techdocs/configuring-ci-cd.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md index ec25684a94..37d1b56692 100644 --- a/docs/features/techdocs/configuring-ci-cd.md +++ b/docs/features/techdocs/configuring-ci-cd.md @@ -24,10 +24,10 @@ REPOSITORY_URL='https://github.com/org/repo' git clone $REPOSITORY_URL # Generate -npx techdocs-cli generate --source-dir ./repo --output-dir ./site +npx @techdocs/cli generate --source-dir ./repo --output-dir ./site # Publish -npx techdocs-cli publish --directory ./site --publisher-type awsS3 --bucket-name --entity +npx @techdocs/cli publish --directory ./site --publisher-type awsS3 --bucket-name --entity # That's it! ``` @@ -64,7 +64,7 @@ Take a look at complete command reference, details, and options. ``` -npx techdocs-cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site +npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site ``` `PATH_TO_REPO` should be the location where the prepare step above clones the @@ -83,5 +83,5 @@ necessary authentication environment variables. - [AWS authentication](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html) ``` -techdocs-cli publish --directory ./site --publisher-type --bucket-name --entity +npx @techdocs/cli publish --directory ./site --publisher-type --bucket-name --entity ``` From 6b6bcb549a21ef59e4ba14e26aba31f4ebc2971a Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Tue, 19 Jan 2021 12:59:34 +0100 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Adam Harvey --- docs/features/techdocs/configuring-ci-cd.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md index 37d1b56692..5da7addb9a 100644 --- a/docs/features/techdocs/configuring-ci-cd.md +++ b/docs/features/techdocs/configuring-ci-cd.md @@ -12,7 +12,7 @@ workflow associated with the repository containing the documentation files. This document explains the steps needed to generate docs on CI and publish to a cloud storage using [`techdocs-cli`](https://github.com/backstage/techdocs-cli). -The steps here target all kinds of CI providers (GitHub actions, Circle CI, +The steps here target all kinds of CI providers (GitHub Actions, CircleCI, Jenkins, etc.) Specific tools for individual providers will also be made available here for simplicity (e.g. A GitHub Actions runner, CircleCI orb, etc.) @@ -44,7 +44,7 @@ the workflow only on changes to files inside the `docs/` directory or The first step on the CI is to clone the repository in a working directory. This is almost always the first step in most CI workflows. -On GitHub actions, you can add a step +On GitHub Actions, you can add a step [`- uses: actions@checkout@v2`](https://github.com/actions/checkout). @@ -67,7 +67,7 @@ complete command reference, details, and options. npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site ``` -`PATH_TO_REPO` should be the location where the prepare step above clones the +`PATH_TO_REPO` should be the location in the file path where the prepare step above clones the repository. ## 4. Publish step @@ -76,7 +76,7 @@ Take a look at [`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the complete command reference, details, and options. -Depending on your cloud storage provider (AWS or Google Cloud), set the +Depending on your cloud storage provider (AWS, Google Cloud, or Azure), set the necessary authentication environment variables. - [Google Cloud authentication](https://cloud.google.com/storage/docs/authentication#libauth) From 3e24d89290ce9357963db5e423a449832705915b Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Tue, 19 Jan 2021 13:18:00 +0100 Subject: [PATCH 4/6] 1. Use --storage-name instead of bucket name 2. Prettier ignore description 3. Refer to CLI readme --- docs/features/techdocs/configuring-ci-cd.md | 58 ++++++++++++--------- 1 file changed, 34 insertions(+), 24 deletions(-) diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md index 5da7addb9a..751785f880 100644 --- a/docs/features/techdocs/configuring-ci-cd.md +++ b/docs/features/techdocs/configuring-ci-cd.md @@ -1,8 +1,8 @@ --- id: configuring-ci-cd title: Configuring CI/CD to generate and publish TechDocs sites -description: - Configuring CI/CD to generate and publish TechDocs sites to cloud storage +# prettier-ignore +description: Configuring CI/CD to generate and publish TechDocs sites to cloud storage --- In the [Recommended deployment setup](./architecture.md#recommended-deployment), @@ -19,30 +19,37 @@ available here for simplicity (e.g. A GitHub Actions runner, CircleCI orb, etc.) A summary of the instructions below looks like this - ```sh +# This is an example script + # Prepare REPOSITORY_URL='https://github.com/org/repo' git clone $REPOSITORY_URL +cd repo # Generate -npx @techdocs/cli generate --source-dir ./repo --output-dir ./site +npx @techdocs/cli generate # Publish -npx @techdocs/cli publish --directory ./site --publisher-type awsS3 --bucket-name --entity - -# That's it! +npx @techdocs/cli publish --publisher-type awsS3 --storage-name --entity ``` +That's it! + +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 The TechDocs workflow should trigger on CI when any changes are made in the -repository containing the documentation files. You can be specific and trigger -the workflow only on changes to files inside the `docs/` directory or -`mkdocs.yml`. +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 -The first step on the CI is to clone the repository in a working directory. This -is almost always the first step in most CI workflows. +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. On GitHub Actions, you can add a step @@ -57,31 +64,34 @@ Eventually we are trying to do a `git clone `. ## 3. Generate step Install [`npx`](https://www.npmjs.com/package/npx) to use it for running -`techdocs-cli`. We are going to use the `techdocs-cli generate` command here. +`techdocs-cli`. Or you can install using `npm install -g @techdocs/cli`. -Take a look at -[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the -complete command reference, details, and options. +We are going to use the +[`techdocs-cli generate`](https://github.com/backstage/techdocs-cli#generate-techdocs-site-from-a-documentation-project) +command in this step. -``` +```sh npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site ``` -`PATH_TO_REPO` should be the location in the file path where the prepare step above clones the -repository. +`PATH_TO_REPO` should be the location in the file path where the prepare step +above clones the repository. ## 4. Publish step -Take a look at -[`techdocs-cli` README](https://github.com/backstage/techdocs-cli) for the -complete command reference, details, and options. - Depending on your cloud storage provider (AWS, Google Cloud, or Azure), set the necessary authentication environment variables. - [Google Cloud authentication](https://cloud.google.com/storage/docs/authentication#libauth) - [AWS authentication](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-environment.html) +And then run the +[`techdocs-cli publish`](https://github.com/backstage/techdocs-cli#publish-generated-techdocs-sites) +command. + +```sh +npx @techdocs/cli publish --publisher-type --storage-name --entity --directory ./site ``` -npx @techdocs/cli publish --directory ./site --publisher-type --bucket-name --entity -``` + +The updated TechDocs site built in this workflow is now ready to be served by +the TechDocs plugin in your Backstage app. From cfc0b73951d3bf61a7326f07fad15263f04498cf Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Tue, 19 Jan 2021 15:05:52 +0100 Subject: [PATCH 5/6] Update docs/features/techdocs/configuring-ci-cd.md Co-authored-by: bodilb <66826349+bodilb@users.noreply.github.com> --- docs/features/techdocs/configuring-ci-cd.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md index 751785f880..1f53c0fcb2 100644 --- a/docs/features/techdocs/configuring-ci-cd.md +++ b/docs/features/techdocs/configuring-ci-cd.md @@ -13,8 +13,8 @@ document explains the steps needed to generate docs on CI and publish to a cloud storage using [`techdocs-cli`](https://github.com/backstage/techdocs-cli). The steps here target all kinds of CI providers (GitHub Actions, CircleCI, -Jenkins, etc.) Specific tools for individual providers will also be made -available here for simplicity (e.g. A GitHub Actions runner, CircleCI orb, etc.) +Jenkins, etc.). Specific tools for individual providers will also be made +available here for simplicity (e.g. a GitHub Actions runner, CircleCI orb, etc.). A summary of the instructions below looks like this - From f47b54614d990aa6e1a9c69306ec08b3b255ef76 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Tue, 19 Jan 2021 16:09:43 +0100 Subject: [PATCH 6/6] docs: Run prettier on techdocs ci/cd tutorial --- docs/features/techdocs/configuring-ci-cd.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/features/techdocs/configuring-ci-cd.md b/docs/features/techdocs/configuring-ci-cd.md index 1f53c0fcb2..5841a02fa8 100644 --- a/docs/features/techdocs/configuring-ci-cd.md +++ b/docs/features/techdocs/configuring-ci-cd.md @@ -14,7 +14,8 @@ storage using [`techdocs-cli`](https://github.com/backstage/techdocs-cli). The steps here target all kinds of CI providers (GitHub Actions, CircleCI, Jenkins, etc.). Specific tools for individual providers will also be made -available here for simplicity (e.g. a GitHub Actions runner, CircleCI orb, etc.). +available here for simplicity (e.g. a GitHub Actions runner, CircleCI orb, +etc.). A summary of the instructions below looks like this -