From b4db2862a41197e07183e87c04d7a92ebc832239 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Wed, 4 Jan 2023 09:51:30 +0100 Subject: [PATCH 1/8] Add cli option --preview-app-bundle-path Signed-off-by: Morgan Bentell --- packages/techdocs-cli/serve.sh | 19 +++++++++++++++++++ packages/techdocs-cli/src/commands/index.ts | 4 ++++ .../techdocs-cli/src/commands/serve/serve.ts | 8 +++++++- 3 files changed, 30 insertions(+), 1 deletion(-) create mode 100755 packages/techdocs-cli/serve.sh diff --git a/packages/techdocs-cli/serve.sh b/packages/techdocs-cli/serve.sh new file mode 100755 index 0000000000..743b49cd8f --- /dev/null +++ b/packages/techdocs-cli/serve.sh @@ -0,0 +1,19 @@ +#!/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 03772d09d7..a164a5e28f 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -251,6 +251,10 @@ 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 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 68d0bbb277..60207b8daf 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/packages/techdocs-cli/src/commands/serve/serve.ts @@ -42,9 +42,15 @@ function findPreviewBundlePath(): string { } } +function getPreviewAppPath(opts: OptionValues): string { + return opts.previewAppBundlePath ?? findPreviewBundlePath(); +} + 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) @@ -117,7 +123,7 @@ export default async function serve(opts: OptionValues) { const port = isDevMode ? backstageBackendPort : backstagePort; const httpServer = new HTTPServer( - findPreviewBundlePath(), + getPreviewAppPath(opts), port, opts.mkdocsPort, opts.verbose, From bc18c902a27cc3f17eaa8096993ca943521aaad0 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Wed, 4 Jan 2023 15:16:39 +0100 Subject: [PATCH 2/8] 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) From 38cdc28135497212f0733f32b02e6df1ebf70211 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Thu, 5 Jan 2023 17:28:26 +0100 Subject: [PATCH 3/8] add --preview-app-port option to serve command Signed-off-by: Morgan Bentell --- packages/techdocs-cli/serve.sh | 0 packages/techdocs-cli/src/commands/index.ts | 15 +++++++++++++++ packages/techdocs-cli/src/commands/serve/serve.ts | 10 ++++------ 3 files changed, 19 insertions(+), 6 deletions(-) create mode 100644 packages/techdocs-cli/serve.sh diff --git a/packages/techdocs-cli/serve.sh b/packages/techdocs-cli/serve.sh new file mode 100644 index 0000000000..e69de29bb2 diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index e6c82ba7f8..b951699104 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -255,6 +255,21 @@ export function registerCommands(program: Command) { '--preview-app-bundle-path ', 'Preview documentation using another web app', ) + .option( + '--preview-app-port ', + 'Port for the preview app to be served on', + '3000', + ) + .hook('preAction', command => { + if ( + command.opts().previewAppPort && + !command.opts().previewAppBundlePath + ) { + command.error( + '--preview-app-port can only be used together with --preview-app-bundle-path', + ); + } + }) .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 ebb984782c..c99ab178f0 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/packages/techdocs-cli/src/commands/serve/serve.ts @@ -56,10 +56,6 @@ export default async function serve(opts: OptionValues) { ? true : false; - // TODO: Backstage app port should also be configurable as a CLI option. However, since we bundle - // a backstage app, we define app.baseUrl in the app-config.yaml. - // Hence, it is complicated to make this configurable. - const backstagePort = 3000; const backstageBackendPort = 7007; const mkdocsDockerAddr = `http://0.0.0.0:${opts.mkdocsPort}`; @@ -119,9 +115,11 @@ export default async function serve(opts: OptionValues) { ); } - const port = isDevMode ? backstageBackendPort : backstagePort; + const port = isDevMode ? backstageBackendPort : opts.previewAppPort; + const previewAppPath = getPreviewAppPath(opts); + console.log({ previewAppPath }); const httpServer = new HTTPServer( - getPreviewAppPath(opts), + previewAppPath, port, opts.mkdocsPort, opts.verbose, From 29113e760af682145b11eed7de2c13ff8d284bd2 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Mon, 9 Jan 2023 10:03:39 +0100 Subject: [PATCH 4/8] update docs and clean up Signed-off-by: Morgan Bentell --- .changeset/dry-camels-scream.md | 2 +- docs/features/techdocs/cli.md | 2 ++ packages/techdocs-cli/cli-report.md | 1 + packages/techdocs-cli/src/commands/serve/serve.ts | 1 - 4 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.changeset/dry-camels-scream.md b/.changeset/dry-camels-scream.md index ea3a7f47b8..ea35cece7a 100644 --- a/.changeset/dry-camels-scream.md +++ b/.changeset/dry-camels-scream.md @@ -2,4 +2,4 @@ '@techdocs/cli': minor --- -Add `--preview-app-bundle-path` option to the `serve` command enabling previewing with apps other than the provided one +Add `--preview-app-bundle-path` and `--preview-app-port` options 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 9d8d2b24d9..1c01441db3 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -95,6 +95,8 @@ Options: --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. + --preview-app-port Port where the preview will be served. + Can only be used with "--preview-app-bundle-path". (default: "3000") -v --verbose Enable verbose output. (default: false) -h, --help display help for command ``` diff --git a/packages/techdocs-cli/cli-report.md b/packages/techdocs-cli/cli-report.md index ad41041dfb..ada61f2542 100644 --- a/packages/techdocs-cli/cli-report.md +++ b/packages/techdocs-cli/cli-report.md @@ -100,6 +100,7 @@ Options: --no-docker --mkdocs-port --preview-app-bundle-path + --preview-app-port -v --verbose -h, --help ``` diff --git a/packages/techdocs-cli/src/commands/serve/serve.ts b/packages/techdocs-cli/src/commands/serve/serve.ts index c99ab178f0..2aea8e4e80 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/packages/techdocs-cli/src/commands/serve/serve.ts @@ -117,7 +117,6 @@ export default async function serve(opts: OptionValues) { const port = isDevMode ? backstageBackendPort : opts.previewAppPort; const previewAppPath = getPreviewAppPath(opts); - console.log({ previewAppPath }); const httpServer = new HTTPServer( previewAppPath, port, From ee36ee8d00de4ecb27bd1bff16eae69d2a806f8a Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Mon, 9 Jan 2023 16:26:29 +0100 Subject: [PATCH 5/8] fix logic Signed-off-by: Morgan Bentell --- packages/techdocs-cli/src/commands/index.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index b951699104..d4303ad306 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -18,6 +18,7 @@ import { Command } from 'commander'; import { TechdocsGenerator } from '@backstage/plugin-techdocs-node'; const defaultDockerImage = TechdocsGenerator.defaultDockerImage; +const defaultPreviewAppPort = '3000'; export function registerCommands(program: Command) { program @@ -258,11 +259,11 @@ export function registerCommands(program: Command) { .option( '--preview-app-port ', 'Port for the preview app to be served on', - '3000', + defaultPreviewAppPort, ) .hook('preAction', command => { if ( - command.opts().previewAppPort && + command.opts().previewAppPort !== defaultPreviewAppPort && !command.opts().previewAppBundlePath ) { command.error( From 0c6323ae8fd7f4daebdff613aeef2b6e0cff5712 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Mon, 9 Jan 2023 16:42:56 +0100 Subject: [PATCH 6/8] fix picky cli-report Signed-off-by: Morgan Bentell --- packages/techdocs-cli/cli-report.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/techdocs-cli/cli-report.md b/packages/techdocs-cli/cli-report.md index ada61f2542..9230fe9f1c 100644 --- a/packages/techdocs-cli/cli-report.md +++ b/packages/techdocs-cli/cli-report.md @@ -99,9 +99,9 @@ Options: --docker-option --no-docker --mkdocs-port + -v --verbose --preview-app-bundle-path --preview-app-port - -v --verbose -h, --help ``` From 5b54a5654ffe02c4c36bf9b3bb0cd1b1aaaac783 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Tue, 10 Jan 2023 09:44:24 +0100 Subject: [PATCH 7/8] remove dev file Signed-off-by: Morgan Bentell --- packages/techdocs-cli/serve.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 packages/techdocs-cli/serve.sh diff --git a/packages/techdocs-cli/serve.sh b/packages/techdocs-cli/serve.sh deleted file mode 100644 index e69de29bb2..0000000000 From 794a87c36c00954fb52a5c96aa5c3065f96333b1 Mon Sep 17 00:00:00 2001 From: Morgan Bentell Date: Tue, 10 Jan 2023 09:52:45 +0100 Subject: [PATCH 8/8] remove autoformatting changes Signed-off-by: Morgan Bentell --- docs/features/techdocs/cli.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index 1c01441db3..682c6a8f8f 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -1,9 +1,7 @@ --- id: cli title: TechDocs CLI - # prettier-ignore - description: TechDocs CLI - a utility command line interface for managing TechDocs sites in Backstage. ---