From 5c269df42496039555dfc30040697f8dba4f59ae Mon Sep 17 00:00:00 2001 From: hainenber Date: Sun, 19 Nov 2023 16:32:27 +0700 Subject: [PATCH 1/6] feat(pkg/techdocs-cli): support passing additional mkdocs-server CLI parameters when run in containerized mode Signed-off-by: hainenber --- packages/techdocs-cli/src/commands/serve/serve.ts | 2 ++ .../techdocs-cli/src/lib/mkdocsServer.test.ts | 15 +++++++++++++++ packages/techdocs-cli/src/lib/mkdocsServer.ts | 3 +++ 3 files changed, 20 insertions(+) diff --git a/packages/techdocs-cli/src/commands/serve/serve.ts b/packages/techdocs-cli/src/commands/serve/serve.ts index 98c9982b21..04a8cff2f6 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/packages/techdocs-cli/src/commands/serve/serve.ts @@ -67,6 +67,7 @@ export default async function serve(opts: OptionValues) { ? mkdocsDockerAddr : mkdocsLocalAddr; const mkdocsConfigFileName = opts.mkdocsConfigFileName; + const mkdocsConfigs = opts.mkdocsConfig.split(' '); const siteName = opts.siteName; const { path: mkdocsYmlPath, configIsTemporary } = await getMkdocsYml('./', { @@ -116,6 +117,7 @@ export default async function serve(opts: OptionValues) { stdoutLogFunc: mkdocsLogFunc, stderrLogFunc: mkdocsLogFunc, mkdocsConfigFileName: mkdocsYmlPath, + mkdocsConfigs: mkdocsConfigs, }); // Wait until mkdocs server has started so that Backstage starts with docs loaded diff --git a/packages/techdocs-cli/src/lib/mkdocsServer.test.ts b/packages/techdocs-cli/src/lib/mkdocsServer.test.ts index 8484c4e242..73203a69e9 100644 --- a/packages/techdocs-cli/src/lib/mkdocsServer.test.ts +++ b/packages/techdocs-cli/src/lib/mkdocsServer.test.ts @@ -97,6 +97,21 @@ describe('runMkdocsServer', () => { expect.objectContaining({}), ); }); + + it('should accept additinoal mkdocs CLI parameters', async () => { + await runMkdocsServer({ mkdocsConfigs: ['--clean', '--strict'] }); + expect(run).toHaveBeenCalledWith( + 'docker', + expect.arrayContaining([ + 'serve', + '--dev-addr', + '0.0.0.0:8000', + '--clean', + '--strict', + ]), + expect.objectContaining({}), + ); + }); }); describe('mkdocs', () => { diff --git a/packages/techdocs-cli/src/lib/mkdocsServer.ts b/packages/techdocs-cli/src/lib/mkdocsServer.ts index 42409acb46..ff412bd87f 100644 --- a/packages/techdocs-cli/src/lib/mkdocsServer.ts +++ b/packages/techdocs-cli/src/lib/mkdocsServer.ts @@ -26,6 +26,7 @@ export const runMkdocsServer = async (options: { stdoutLogFunc?: LogFunc; stderrLogFunc?: LogFunc; mkdocsConfigFileName?: string; + mkdocsConfigs?: string[]; }): Promise => { const port = options.port ?? '8000'; const useDocker = options.useDocker ?? true; @@ -55,6 +56,7 @@ export const runMkdocsServer = async (options: { ...(options.mkdocsConfigFileName ? ['--config-file', options.mkdocsConfigFileName] : []), + ...(options.mkdocsConfigs ?? []), ], { stdoutLogFunc: options.stdoutLogFunc, @@ -72,6 +74,7 @@ export const runMkdocsServer = async (options: { ...(options.mkdocsConfigFileName ? ['--config-file', options.mkdocsConfigFileName] : []), + ...(options.mkdocsConfigs ?? []), ], { stdoutLogFunc: options.stdoutLogFunc, From b2dccad7b3dd9cbb20fc2635a973e302954902d8 Mon Sep 17 00:00:00 2001 From: hainenber Date: Sun, 19 Nov 2023 16:33:27 +0700 Subject: [PATCH 2/6] chore: add changeset Signed-off-by: hainenber --- .changeset/tricky-donkeys-do.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/tricky-donkeys-do.md diff --git a/.changeset/tricky-donkeys-do.md b/.changeset/tricky-donkeys-do.md new file mode 100644 index 0000000000..8859f012ba --- /dev/null +++ b/.changeset/tricky-donkeys-do.md @@ -0,0 +1,5 @@ +--- +'@techdocs/cli': minor +--- + +support passing additional mkdocs-server CLI parameters when run in containerized mode From 549ca5e3c4e50fa6f81155d12125d26cd9e91cc7 Mon Sep 17 00:00:00 2001 From: hainenber Date: Sun, 19 Nov 2023 16:40:45 +0700 Subject: [PATCH 3/6] fix(pkg/techdocs-cli): specify new opt Signed-off-by: hainenber --- docs/features/techdocs/cli.md | 1 + packages/techdocs-cli/src/commands/index.ts | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index 9704b9b21b..6a2407372f 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -91,6 +91,7 @@ Options: --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-configs Extra mkdocs server to pass to mkdocs running in containerized 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. diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index 10a00da513..3052575366 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -289,6 +289,10 @@ export function registerCommands(program: Command) { '-c, --mkdocs-config-file-name ', 'Mkdocs config file name', ) + .option( + '--mkdocs-configs', + 'Additional parameters to pass to containerized mkdocs', + ) .hook('preAction', command => { if ( command.opts().previewAppPort !== defaultPreviewAppPort && From 69b2f7bf3bb9f437c3c71b4d40f4d81149462eb4 Mon Sep 17 00:00:00 2001 From: hainenber Date: Mon, 20 Nov 2023 21:46:41 +0700 Subject: [PATCH 4/6] fix(techdocs-cli): limit supported mkdocs flags Signed-off-by: hainenber --- docs/features/techdocs/cli.md | 4 +++- packages/techdocs-cli/cli-report.md | 3 +++ packages/techdocs-cli/src/commands/index.ts | 15 +++++++++++++-- packages/techdocs-cli/src/commands/serve/serve.ts | 5 +++-- .../techdocs-cli/src/lib/mkdocsServer.test.ts | 5 ++++- packages/techdocs-cli/src/lib/mkdocsServer.ts | 12 +++++++++--- 6 files changed, 35 insertions(+), 9 deletions(-) diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index 6a2407372f..e7b3aff057 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -91,7 +91,9 @@ Options: --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-configs Extra mkdocs server to pass to mkdocs running in containerized environment. + --mkdocs-parameter-clean Pass "--clean" parameter to mkdocs server running in containerized environment. + --mkdocs-parameter-dirty Pass "--dirty" parameter to mkdocs server running in containerized environment. + --mkdocs-parameter-strict Pass "--strict" parameter to mkdocs server running in containerized 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. diff --git a/packages/techdocs-cli/cli-report.md b/packages/techdocs-cli/cli-report.md index 890718b0d2..9c155473ef 100644 --- a/packages/techdocs-cli/cli-report.md +++ b/packages/techdocs-cli/cli-report.md @@ -107,6 +107,9 @@ Options: --preview-app-bundle-path --preview-app-port -c, --mkdocs-config-file-name + --mkdocs-parameter-clean + --mkdocs-parameter-dirty + --mkdocs-parameter-strict -h, --help ``` diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index 3052575366..2d5ff98e77 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -290,8 +290,19 @@ export function registerCommands(program: Command) { 'Mkdocs config file name', ) .option( - '--mkdocs-configs', - 'Additional parameters to pass to containerized mkdocs', + '--mkdocs-parameter-clean', + 'Pass "--clean" parameter to mkdocs server running in containerized environment', + false, + ) + .option( + '--mkdocs-parameter-dirty', + 'Pass "--dirty" parameter to mkdocs server running in containerized environment', + false, + ) + .option( + '--mkdocs-parameter-strict', + 'Pass "--strict" parameter to mkdocs server running in containerized environment', + false, ) .hook('preAction', command => { if ( diff --git a/packages/techdocs-cli/src/commands/serve/serve.ts b/packages/techdocs-cli/src/commands/serve/serve.ts index 04a8cff2f6..47cfbe8a22 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/packages/techdocs-cli/src/commands/serve/serve.ts @@ -67,7 +67,6 @@ export default async function serve(opts: OptionValues) { ? mkdocsDockerAddr : mkdocsLocalAddr; const mkdocsConfigFileName = opts.mkdocsConfigFileName; - const mkdocsConfigs = opts.mkdocsConfig.split(' '); const siteName = opts.siteName; const { path: mkdocsYmlPath, configIsTemporary } = await getMkdocsYml('./', { @@ -117,7 +116,9 @@ export default async function serve(opts: OptionValues) { stdoutLogFunc: mkdocsLogFunc, stderrLogFunc: mkdocsLogFunc, mkdocsConfigFileName: mkdocsYmlPath, - mkdocsConfigs: mkdocsConfigs, + mkdocsParameterClean: opts.mkdocsParameterClean, + mkdocsParameterDirty: opts.mkdocsParameterDirty, + mkdocsParameterStrict: opts.mkdocsParameterStrict, }); // Wait until mkdocs server has started so that Backstage starts with docs loaded diff --git a/packages/techdocs-cli/src/lib/mkdocsServer.test.ts b/packages/techdocs-cli/src/lib/mkdocsServer.test.ts index 73203a69e9..83f9c9f382 100644 --- a/packages/techdocs-cli/src/lib/mkdocsServer.test.ts +++ b/packages/techdocs-cli/src/lib/mkdocsServer.test.ts @@ -99,7 +99,10 @@ describe('runMkdocsServer', () => { }); it('should accept additinoal mkdocs CLI parameters', async () => { - await runMkdocsServer({ mkdocsConfigs: ['--clean', '--strict'] }); + await runMkdocsServer({ + mkdocsParameterClean: true, + mkdocsParameterStrict: true, + }); expect(run).toHaveBeenCalledWith( 'docker', expect.arrayContaining([ diff --git a/packages/techdocs-cli/src/lib/mkdocsServer.ts b/packages/techdocs-cli/src/lib/mkdocsServer.ts index ff412bd87f..dced19cb7a 100644 --- a/packages/techdocs-cli/src/lib/mkdocsServer.ts +++ b/packages/techdocs-cli/src/lib/mkdocsServer.ts @@ -26,7 +26,9 @@ export const runMkdocsServer = async (options: { stdoutLogFunc?: LogFunc; stderrLogFunc?: LogFunc; mkdocsConfigFileName?: string; - mkdocsConfigs?: string[]; + mkdocsParameterClean?: boolean; + mkdocsParameterDirty?: boolean; + mkdocsParameterStrict?: boolean; }): Promise => { const port = options.port ?? '8000'; const useDocker = options.useDocker ?? true; @@ -56,7 +58,9 @@ export const runMkdocsServer = async (options: { ...(options.mkdocsConfigFileName ? ['--config-file', options.mkdocsConfigFileName] : []), - ...(options.mkdocsConfigs ?? []), + ...(options.mkdocsParameterClean ? '--clean' : []), + ...(options.mkdocsParameterDirty ? '--dirty' : []), + ...(options.mkdocsParameterStrict ? '--strict' : []), ], { stdoutLogFunc: options.stdoutLogFunc, @@ -74,7 +78,9 @@ export const runMkdocsServer = async (options: { ...(options.mkdocsConfigFileName ? ['--config-file', options.mkdocsConfigFileName] : []), - ...(options.mkdocsConfigs ?? []), + ...(options.mkdocsParameterClean ? '--clean' : []), + ...(options.mkdocsParameterDirty ? '--dirty' : []), + ...(options.mkdocsParameterStrict ? '--strict' : []), ], { stdoutLogFunc: options.stdoutLogFunc, From 716dd37404b4560821cb5daa7ca23897957ec45b Mon Sep 17 00:00:00 2001 From: hainenber Date: Tue, 21 Nov 2023 22:37:02 +0700 Subject: [PATCH 5/6] fix(pkg/techdocs): correct dirtyreload arg for mkdocs Also correct array-like elements for rest operator Signed-off-by: hainenber --- .changeset/tricky-donkeys-do.md | 2 +- docs/features/techdocs/cli.md | 2 +- packages/techdocs-cli/cli-report.md | 2 +- packages/techdocs-cli/src/commands/index.ts | 4 ++-- packages/techdocs-cli/src/commands/serve/serve.ts | 2 +- packages/techdocs-cli/src/lib/mkdocsServer.ts | 14 +++++++------- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.changeset/tricky-donkeys-do.md b/.changeset/tricky-donkeys-do.md index 8859f012ba..573aa53135 100644 --- a/.changeset/tricky-donkeys-do.md +++ b/.changeset/tricky-donkeys-do.md @@ -2,4 +2,4 @@ '@techdocs/cli': minor --- -support passing additional mkdocs-server CLI parameters when run in containerized mode +support passing additional mkdocs-server CLI parameters (--dirtyreload, --strict and --clean) when run in containerized mode diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index e7b3aff057..97ed881922 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -92,7 +92,7 @@ Options: (can be added multiple times). --no-docker Do not use Docker, use MkDocs executable in current user environment. --mkdocs-parameter-clean Pass "--clean" parameter to mkdocs server running in containerized environment. - --mkdocs-parameter-dirty Pass "--dirty" parameter to mkdocs server running in containerized environment. + --mkdocs-parameter-dirtyreload Pass "--dirtyreload" parameter to mkdocs server running in containerized environment. --mkdocs-parameter-strict Pass "--strict" parameter to mkdocs server running in containerized 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. diff --git a/packages/techdocs-cli/cli-report.md b/packages/techdocs-cli/cli-report.md index 9c155473ef..c50a320868 100644 --- a/packages/techdocs-cli/cli-report.md +++ b/packages/techdocs-cli/cli-report.md @@ -108,7 +108,7 @@ Options: --preview-app-port -c, --mkdocs-config-file-name --mkdocs-parameter-clean - --mkdocs-parameter-dirty + --mkdocs-parameter-dirtyreload --mkdocs-parameter-strict -h, --help ``` diff --git a/packages/techdocs-cli/src/commands/index.ts b/packages/techdocs-cli/src/commands/index.ts index 2d5ff98e77..d7c98db37c 100644 --- a/packages/techdocs-cli/src/commands/index.ts +++ b/packages/techdocs-cli/src/commands/index.ts @@ -295,8 +295,8 @@ export function registerCommands(program: Command) { false, ) .option( - '--mkdocs-parameter-dirty', - 'Pass "--dirty" parameter to mkdocs server running in containerized environment', + '--mkdocs-parameter-dirtyreload', + 'Pass "--dirtyreload" parameter to mkdocs server running in containerized environment', false, ) .option( diff --git a/packages/techdocs-cli/src/commands/serve/serve.ts b/packages/techdocs-cli/src/commands/serve/serve.ts index 47cfbe8a22..de681c2de4 100644 --- a/packages/techdocs-cli/src/commands/serve/serve.ts +++ b/packages/techdocs-cli/src/commands/serve/serve.ts @@ -117,7 +117,7 @@ export default async function serve(opts: OptionValues) { stderrLogFunc: mkdocsLogFunc, mkdocsConfigFileName: mkdocsYmlPath, mkdocsParameterClean: opts.mkdocsParameterClean, - mkdocsParameterDirty: opts.mkdocsParameterDirty, + mkdocsParameterDirtyReload: opts.mkdocsParameterDirtyReload, mkdocsParameterStrict: opts.mkdocsParameterStrict, }); diff --git a/packages/techdocs-cli/src/lib/mkdocsServer.ts b/packages/techdocs-cli/src/lib/mkdocsServer.ts index dced19cb7a..3c7f9ea5ec 100644 --- a/packages/techdocs-cli/src/lib/mkdocsServer.ts +++ b/packages/techdocs-cli/src/lib/mkdocsServer.ts @@ -27,7 +27,7 @@ export const runMkdocsServer = async (options: { stderrLogFunc?: LogFunc; mkdocsConfigFileName?: string; mkdocsParameterClean?: boolean; - mkdocsParameterDirty?: boolean; + mkdocsParameterDirtyReload?: boolean; mkdocsParameterStrict?: boolean; }): Promise => { const port = options.port ?? '8000'; @@ -58,9 +58,9 @@ export const runMkdocsServer = async (options: { ...(options.mkdocsConfigFileName ? ['--config-file', options.mkdocsConfigFileName] : []), - ...(options.mkdocsParameterClean ? '--clean' : []), - ...(options.mkdocsParameterDirty ? '--dirty' : []), - ...(options.mkdocsParameterStrict ? '--strict' : []), + ...(options.mkdocsParameterClean ? ['--clean'] : []), + ...(options.mkdocsParameterDirtyReload ? ['--dirty'] : []), + ...(options.mkdocsParameterStrict ? ['--strict'] : []), ], { stdoutLogFunc: options.stdoutLogFunc, @@ -78,9 +78,9 @@ export const runMkdocsServer = async (options: { ...(options.mkdocsConfigFileName ? ['--config-file', options.mkdocsConfigFileName] : []), - ...(options.mkdocsParameterClean ? '--clean' : []), - ...(options.mkdocsParameterDirty ? '--dirty' : []), - ...(options.mkdocsParameterStrict ? '--strict' : []), + ...(options.mkdocsParameterClean ? ['--clean'] : []), + ...(options.mkdocsParameterDirtyReload ? ['--dirtyreload'] : []), + ...(options.mkdocsParameterStrict ? ['--strict'] : []), ], { stdoutLogFunc: options.stdoutLogFunc, From 68ae3df03936cefadf50773de7a453b69795ef0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C4=90=E1=BB=97=20Tr=E1=BB=8Dng=20H=E1=BA=A3i?= <41283691+hainenber@users.noreply.github.com> Date: Wed, 22 Nov 2023 00:57:58 +0700 Subject: [PATCH 6/6] Update mkdocsServer.ts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Andre Wanlin <67169551+awanlin@users.noreply.github.com> Signed-off-by: Đỗ Trọng Hải <41283691+hainenber@users.noreply.github.com> --- packages/techdocs-cli/src/lib/mkdocsServer.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/techdocs-cli/src/lib/mkdocsServer.ts b/packages/techdocs-cli/src/lib/mkdocsServer.ts index 3c7f9ea5ec..a793643367 100644 --- a/packages/techdocs-cli/src/lib/mkdocsServer.ts +++ b/packages/techdocs-cli/src/lib/mkdocsServer.ts @@ -59,7 +59,7 @@ export const runMkdocsServer = async (options: { ? ['--config-file', options.mkdocsConfigFileName] : []), ...(options.mkdocsParameterClean ? ['--clean'] : []), - ...(options.mkdocsParameterDirtyReload ? ['--dirty'] : []), + ...(options.mkdocsParameterDirtyReload ? ['--dirtyreload'] : []), ...(options.mkdocsParameterStrict ? ['--strict'] : []), ], {