diff --git a/.changeset/friendly-carpets-repeat.md b/.changeset/friendly-carpets-repeat.md index d42a28a8a616d..e2ee348cf4c33 100644 --- a/.changeset/friendly-carpets-repeat.md +++ b/.changeset/friendly-carpets-repeat.md @@ -11,11 +11,11 @@ _Breaking changes_ Step-by-step guide to configure GCS is available here https://backstage.io/docs/features/techdocs/using-cloud-storage Set `techdocs.publisher.type` to `'local'` if you want to continue using local filesystem to store TechDocs files. -2. `techdocs.builder` is now required and can be set to `'local'` or `'ci'`. (Set it to `'local'` for now, since CI/CD build +2. `techdocs.builder` is now required and can be set to `'local'` or `'external'`. (Set it to `'local'` for now, since CI/CD build workflow for TechDocs will be available soon (in few weeks)). If builder is set to 'local' and you open a TechDocs page, `techdocs-backend` will try to build the docs, publish to storage and show the generated docs afterwords. - If builder is set to `'ci'`, `techdocs-backend` will only fetch the docs and will NOT try to build and publish. In this case of 'ci', + If builder is set to `'external'`, `techdocs-backend` will only fetch the docs and will NOT try to build and publish. In this case of `'external'`, we assume that docs are being built in the CI/CD pipeline of the repository. TechDocs will not assume a default value for `techdocs.builder`. It is better to explicitly define it in the `app-config.yaml`. diff --git a/.changeset/six-mugs-camp.md b/.changeset/six-mugs-camp.md index 376a406b1dac8..a27a25a15b723 100644 --- a/.changeset/six-mugs-camp.md +++ b/.changeset/six-mugs-camp.md @@ -17,4 +17,4 @@ instead of An instance of `publisher` can either be a local filesystem publisher or a Google Cloud Storage publisher. Read more about the configs here https://backstage.io/docs/features/techdocs/configuration -(You will also have to update `techdocs.storage.type` to `local` or `google_gcs`. And `techdocs.builder` to either `local` or `ci`.) +(You will also have to update `techdocs.storage.type` to `local` or `google_gcs`. And `techdocs.builder` to either `local` or `external`.) diff --git a/app-config.yaml b/app-config.yaml index f8529f834bcf5..81538d8f61e04 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -72,7 +72,7 @@ organization: techdocs: requestUrl: http://localhost:7000/api/techdocs storageUrl: http://localhost:7000/api/techdocs/static/docs - builder: 'local' # Alternatives - 'ci' + builder: 'local' # Alternatives - 'external' generators: techdocs: 'docker' # Alternatives - 'local' publisher: diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md index 5c1b9ab5c0e21..73e0cc0f6688a 100644 --- a/docs/features/techdocs/configuration.md +++ b/docs/features/techdocs/configuration.md @@ -27,7 +27,7 @@ techdocs: # generators.techdocs can have two values: 'docker' or 'local'. This is to determine how to run the generator - whether to # spin up the techdocs-container docker image or to run mkdocs locally (assuming all the dependencies are taken care of). - # You want to change this to 'local' if you are running Backstage using your own customer Docker setup and want to avoid running + # You want to change this to 'local' if you are running Backstage using your own custom Docker setup and want to avoid running # into Docker in Docker situation. Read more here # https://backstage.io/docs/features/techdocs/getting-started#disable-docker-in-docker-situation-optional @@ -35,12 +35,12 @@ techdocs: techdocs: 'docker' - # techdocs.builder can be either 'local' or 'ci. + # techdocs.builder can be either 'local' or 'external. # If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to build the docs, publish to storage # and show the generated docs afterwords. This is the "Basic" setup of the TechDocs Architecture. - # If builder is set to 'ci', techdocs-backend will only fetch the docs and will NOT try to build and publish. In this case of 'ci', - # we assume that docs are being built in the CI/CD pipeline of the repository. This is the "Recommended" setup of the architecture. - # Read more here https://backstage.io/docs/features/techdocs/architecture + # If builder is set to 'external', techdocs-backend will only fetch the docs and will NOT try to build and publish. In this case of 'external', + # we assume that docs are being built by an external process (e.g. in the CI/CD pipeline of the repository). This is the "Recommended" setup of + # the architecture. Read more here https://backstage.io/docs/features/techdocs/architecture builder: 'local' diff --git a/plugins/techdocs-backend/src/service/router.ts b/plugins/techdocs-backend/src/service/router.ts index 97a950d8f2118..a13f25790a65c 100644 --- a/plugins/techdocs-backend/src/service/router.ts +++ b/plugins/techdocs-backend/src/service/router.ts @@ -121,8 +121,8 @@ export async function createRouter({ } // techdocs-backend will only try to build documentation for an entity if techdocs.builder is set to 'local' - // If set to 'ci', it will only try to fetch and assume that that CI/CD pipeline of the repository hosting the - // entity's documentation is responsible for building and publishing documentation to the storage provider. + // If set to 'external', it will only try to fetch and assume that an external process (e.g. CI/CD pipeline + // of the repository) is responsible for building and publishing documentation to the storage provider. if (config.getString('techdocs.builder') === 'local') { const docsBuilder = new DocsBuilder({ preparers, diff --git a/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx b/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx index d3b3bda8bc689..e19cb6963183f 100644 --- a/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx @@ -27,11 +27,12 @@ export const TechDocsNotFound = ({ errorMessage }: Props) => { ); let additionalInfo = ''; - if (techdocsBuilder === 'ci') { + if (techdocsBuilder !== 'local') { additionalInfo = - "Note that you have set techdocs.builder to 'ci' in your config, which means this Backstage app will not " + - "build docs if they are not found. Make sure the project's CI/CD pipeline builds and publishes docs. Or " + - "change techdocs.builder to 'local' to build docs from this Backstage instance."; + "Note that techdocs.builder is not set to 'local' in your config, which means this Backstage app will not " + + "build docs if they are not found. Make sure the project's docs are generated and published by some external " + + "process (e.g. CI/CD pipeline). Or change techdocs.builder to 'local' to build docs from this Backstage " + + 'instance.'; } return (