diff --git a/.changeset/friendly-carpets-repeat.md b/.changeset/friendly-carpets-repeat.md index e2ee348cf4..7fb0d2f6eb 100644 --- a/.changeset/friendly-carpets-repeat.md +++ b/.changeset/friendly-carpets-repeat.md @@ -13,9 +13,9 @@ _Breaking changes_ 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 + If builder is set to 'local' and you open a TechDocs page, `techdocs-backend` will try to generate the docs, publish to storage and show the generated docs afterwords. - 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'`, + If builder is set to `'external'`, `techdocs-backend` will only fetch the docs and will NOT try to generate 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`. @@ -30,7 +30,7 @@ Based on the config `techdocs.publisher.type`, the publisher could be either Loc 4. `techdocs.storageUrl` is now a required config. Should be `http://localhost:7000/api/techdocs/static/docs` in most setups. -5. Parts of `@backstage/plugin-techdocs-backend` have been moved to a new package `@backstage/techdocs-common` to build docs. Also to publish docs +5. Parts of `@backstage/plugin-techdocs-backend` have been moved to a new package `@backstage/techdocs-common` to generate docs. Also to publish docs to-and-fro between TechDocs and a storage (either local or external). However, a Backstage app does NOT need to import the `techdocs-common` package - app should only import `@backstage/plugin-techdocs` and `@backstage/plugin-techdocs-backend`. diff --git a/docs/features/techdocs/architecture.md b/docs/features/techdocs/architecture.md index f502b3836e..a71a23cabb 100644 --- a/docs/features/techdocs/architecture.md +++ b/docs/features/techdocs/architecture.md @@ -50,7 +50,7 @@ built. We assume each entity lives in a repository somewhere (GitHub, GitLab, etc.). We recommend using a CI/CD pipeline with the repository that has a dedicated -step/job to build docs for TechDocs. The generated static files are then stored +step/job to generate docs for TechDocs. The generated static files are then stored in a cloud storage solution of your choice. [Track progress here](https://github.com/backstage/backstage/issues/3096). @@ -60,9 +60,9 @@ your configured storage solution for the necessary files and returns them to TechDocs Reader. We will provide instructions, scripts and/or templates (e.g. GitHub actions) to -build docs in your CI/CD system. +generate docs in your CI/CD system. [Track progress here.](https://github.com/backstage/backstage/issues/3400) You -will be able to use `techdocs-cli` to build docs and publish the generated docs +will be able to use `techdocs-cli` to generate docs and publish the generated docs site files to your cloud storage system. Note about caching: We have noticed internally that some storage providers can @@ -120,7 +120,7 @@ docs site in real-time?** A: Generating the content from Markdown on the fly is not optimal (although that is how the basic out-of-the-box setup is implemented). Storage solutions act as a cache for the generated static content. TechDocs is also currently built on -MkDocs which does not allow us to build docs per-page, so we would have to build +MkDocs which does not allow us to generate docs per-page, so we would have to build all docs for a entity on every request. # Future work diff --git a/docs/features/techdocs/configuration.md b/docs/features/techdocs/configuration.md index 73e0cc0f66..f3be54a4de 100644 --- a/docs/features/techdocs/configuration.md +++ b/docs/features/techdocs/configuration.md @@ -36,9 +36,9 @@ techdocs: # 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 + # If builder is set to 'local' and you open a TechDocs page, techdocs-backend will try to generate 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 'external', techdocs-backend will only fetch the docs and will NOT try to build and publish. In this case of 'external', + # If builder is set to 'external', techdocs-backend will only fetch the docs and will NOT try to generate 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 diff --git a/packages/techdocs-common/src/stages/generate/helpers.ts b/packages/techdocs-common/src/stages/generate/helpers.ts index 13344b8542..773b542517 100644 --- a/packages/techdocs-common/src/stages/generate/helpers.ts +++ b/packages/techdocs-common/src/stages/generate/helpers.ts @@ -209,7 +209,7 @@ export const getRepoUrlFromLocationAnnotation = ( }; /** - * Update the mkdocs.yml file before TechDocs generator uses it to build docs site. + * Update the mkdocs.yml file before TechDocs generator uses it to generate docs site. * * List of tasks: * - Add repo_url if it does not exists diff --git a/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx b/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx index e19cb69631..cdacc1cb7e 100644 --- a/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx +++ b/plugins/techdocs/src/reader/components/TechDocsNotFound.tsx @@ -30,8 +30,8 @@ export const TechDocsNotFound = ({ errorMessage }: Props) => { if (techdocsBuilder !== 'local') { additionalInfo = "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 " + + "generate 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 generate docs from this Backstage " + 'instance.'; }