From bc18c902a27cc3f17eaa8096993ca943521aaad0 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Wed, 4 Jan 2023 15:16:39 +0100 Subject: [PATCH] clean up and update documentation, changeset and cli-report Signed-off-by: Morgan Bentell --- .changeset/dry-camels-scream.md | 5 ++++ docs/features/techdocs/cli.md | 24 ++++++++++++------- packages/techdocs-cli/cli-report.md | 1 + packages/techdocs-cli/serve.sh | 19 --------------- packages/techdocs-cli/src/commands/index.ts | 2 +- .../techdocs-cli/src/commands/serve/serve.ts | 2 -- 6 files changed, 23 insertions(+), 30 deletions(-) create mode 100644 .changeset/dry-camels-scream.md delete mode 100755 packages/techdocs-cli/serve.sh diff --git a/.changeset/dry-camels-scream.md b/.changeset/dry-camels-scream.md new file mode 100644 index 0000000000..ea3a7f47b8 --- /dev/null +++ b/.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 diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index 06eb83dfca..9d8d2b24d9 100644 --- a/docs/features/techdocs/cli.md +++ b/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 The mkdocs docker container to use (default: "spotify/techdocs") - --docker-entrypoint Override the image entrypoint - --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 for MkDocs server to use (default: "8000") - -v --verbose Enable verbose output. (default: false) - -h, --help display help for command + -i, --docker-image The mkdocs docker container to use (default: "spotify/techdocs") + --docker-entrypoint Override the image entrypoint + --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 for MkDocs server to use (default: "8000") + --preview-app-bundle-path 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 diff --git a/packages/techdocs-cli/cli-report.md b/packages/techdocs-cli/cli-report.md index cf5b2caf0f..ad41041dfb 100644 --- a/packages/techdocs-cli/cli-report.md +++ b/packages/techdocs-cli/cli-report.md @@ -99,6 +99,7 @@ Options: --docker-option --no-docker --mkdocs-port + --preview-app-bundle-path -v --verbose -h, --help ``` diff --git a/packages/techdocs-cli/serve.sh b/packages/techdocs-cli/serve.sh deleted file mode 100755 index 743b49cd8f..0000000000 --- a/packages/techdocs-cli/serve.sh +++ /dev/null @@ -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 diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index a164a5e28f..e6c82ba7f8 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -252,7 +252,7 @@ export function registerCommands(program: Command) { .option('--mkdocs-port ', 'Port for MkDocs server to use', '8000') .option('-v --verbose', 'Enable verbose output.', false) .option( - '--preview-app-bundle-path ', + '--preview-app-bundle-path ', 'Preview documentation using another web app', ) .action(lazy(() => import('./serve/serve').then(m => m.default))); diff --git a/packages/techdocs-cli/src/commands/serve/serve.ts b/packages/techdocs-cli/src/commands/serve/serve.ts index 60207b8daf..ebb984782c 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/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)