clean up and update documentation, changeset and cli-report

Signed-off-by: Morgan Bentell <mbentell@spotify.com>

.changeset/dry-camels-scream.md

@@ -0,0 +1,5 @@
+---
+'@techdocs/cli': minor
+---
+
+Add `--preview-app-bundle-path` option to the `serve` command enabling previewing with apps other than the provided one

docs/features/techdocs/cli.md

@@ -1,7 +1,9 @@
 ---
 id: cli
 title: TechDocs CLI
+
 # prettier-ignore
+
 description: TechDocs CLI - a utility command line interface for managing TechDocs sites in Backstage.
 ---
 
@@ -70,6 +72,11 @@ a Backstage app server on port 3000. The Backstage app has a custom TechDocs API
 implementation, which uses the MkDocs preview server as a proxy to fetch the
 generated documentation files and assets.
 
+Backstage instances might differ from the provided preview app in appearance and
+behavior. To preview documentation with a different app, use
+`--preview-app-bundle-path` with a path to the bundle of the app to use instead.
+Typically, a `dist` or `build` directory.
+
 NOTE: When using a custom `techdocs` docker image, make sure the entry point is
 also `ENTRYPOINT ["mkdocs"]` or override with `--docker-entrypoint`.
 
@@ -81,14 +88,15 @@ Usage: techdocs-cli serve [options]
 Serve a documentation project locally in a Backstage app-like environment
 
 Options:
-  -i, --docker-image <DOCKER_IMAGE>        The mkdocs docker container to use (default: "spotify/techdocs")
-  --docker-entrypoint <DOCKER_ENTRYPOINT>  Override the image entrypoint
-  --docker-option <DOCKER_OPTION...>       Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12"
-                                           (can be added multiple times).
-  --no-docker                              Do not use Docker, use MkDocs executable in current user environment.
-  --mkdocs-port <PORT>                     Port for MkDocs server to use (default: "8000")
-  -v --verbose                             Enable verbose output. (default: false)
-  -h, --help                               display help for command
+  -i, --docker-image <DOCKER_IMAGE>           The mkdocs docker container to use (default: "spotify/techdocs")
+  --docker-entrypoint <DOCKER_ENTRYPOINT>     Override the image entrypoint
+  --docker-option <DOCKER_OPTION...>          Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12"
+                                              (can be added multiple times).
+  --no-docker                                 Do not use Docker, use MkDocs executable in current user environment.
+  --mkdocs-port <PORT>                        Port for MkDocs server to use (default: "8000")
+  --preview-app-bundle-path <PATH_TO_BUNDLE>  Preview documentation using a web app other than the included one.
+  -v --verbose                                Enable verbose output. (default: false)
+  -h, --help                                  display help for command
 ```
 
 ### Generate TechDocs site from a documentation project

packages/techdocs-cli/cli-report.md

@@ -99,6 +99,7 @@ Options:
   --docker-option <DOCKER_OPTION...>
   --no-docker
   --mkdocs-port <PORT>
+  --preview-app-bundle-path <PATH_TO_BUNDLE>
   -v --verbose
   -h, --help
 ```

packages/techdocs-cli/serve.sh

@@ -1,19 +0,0 @@
-#!/bin/bash
-
-set -e
-
-## build app
-cd ~/kod/backstage-frontend/packages/techdocs-cli-embedded-app-4-spotify/
-yarn build
-
-## run cli
-REPO_ROOT=~/kod/backstage
-
-cd $REPO_ROOT/packages/techdocs-cli/src/
-rm -rf dist
-cp -r ~/kod/backstage-frontend/packages/techdocs-cli-embedded-app-4-spotify/dist .
-
-cd $REPO_ROOT
-yarn workspace @techdocs/cli build
-cd ~/kod/docs/
-~/kod/backstage/packages/techdocs-cli/bin/techdocs-cli serve --preview-app-bundle-path ~/kod/backstage/packages/techdocs-cli/src/dist

packages/techdocs-cli/src/commands/index.ts

@@ -252,7 +252,7 @@ export function registerCommands(program: Command) {
     .option('--mkdocs-port <PORT>', 'Port for MkDocs server to use', '8000')
     .option('-v --verbose', 'Enable verbose output.', false)
     .option(
-      '--preview-app-bundle-path <PATH>',
+      '--preview-app-bundle-path <PATH_TO_BUNDLE>',
       'Preview documentation using another web app',
     )
     .action(lazy(() => import('./serve/serve').then(m => m.default)));

packages/techdocs-cli/src/commands/serve/serve.ts

@@ -49,8 +49,6 @@ function getPreviewAppPath(opts: OptionValues): string {
 export default async function serve(opts: OptionValues) {
   const logger = createLogger({ verbose: opts.verbose });
 
-  console.log(opts.previewAppBundlePath);
-
   // Determine if we want to run in local dev mode or not
   // This will run the backstage http server on a different port and only used
   // for proxying mkdocs to the backstage app running locally (e.g. with webpack-dev-server)