techdocs: Use 'local' and 'external' for alternatives for techdocs.bu…

…ilder config

Co-authored-by: freben <freben@gmail.com>

.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`.
 

.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`.)

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:

docs/features/techdocs/configuration.md

@@ -27,20 +27,20 @@ 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
 
   generators:
     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'
 

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,

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 (