From d9bbe4182e401a6d331d04ae929ab840dde82be0 Mon Sep 17 00:00:00 2001 From: Will Gibson <8738245+WillGibson@users.noreply.github.com> Date: Thu, 23 Jan 2025 09:40:32 +0000 Subject: [PATCH] docs: DBTP-1332 Nest commands list for easier navigation (#734) --- dbt_platform_helper/COMMANDS.md | 68 +++++++++---------- .../templates/COMMANDS.md.jinja | 8 ++- .../test-docs/expected_output.md | 6 +- utils/create_command_docs.py | 8 ++- 4 files changed, 47 insertions(+), 43 deletions(-) diff --git a/dbt_platform_helper/COMMANDS.md b/dbt_platform_helper/COMMANDS.md index 330d06b26..f2140a881 100644 --- a/dbt_platform_helper/COMMANDS.md +++ b/dbt_platform_helper/COMMANDS.md @@ -1,40 +1,40 @@ # Commands Reference - [platform-helper](#platform-helper) -- [platform-helper application](#platform-helper-application) -- [platform-helper application container-stats](#platform-helper-application-container-stats) -- [platform-helper application task-stats](#platform-helper-application-task-stats) -- [platform-helper codebase](#platform-helper-codebase) -- [platform-helper codebase prepare](#platform-helper-codebase-prepare) -- [platform-helper codebase list](#platform-helper-codebase-list) -- [platform-helper codebase build](#platform-helper-codebase-build) -- [platform-helper codebase deploy](#platform-helper-codebase-deploy) -- [platform-helper conduit](#platform-helper-conduit) -- [platform-helper config](#platform-helper-config) -- [platform-helper config validate](#platform-helper-config-validate) -- [platform-helper config aws](#platform-helper-config-aws) -- [platform-helper copilot](#platform-helper-copilot) -- [platform-helper copilot make-addons](#platform-helper-copilot-make-addons) -- [platform-helper environment](#platform-helper-environment) -- [platform-helper environment offline](#platform-helper-environment-offline) -- [platform-helper environment online](#platform-helper-environment-online) -- [platform-helper environment generate](#platform-helper-environment-generate) -- [platform-helper environment generate-terraform](#platform-helper-environment-generate-terraform) -- [platform-helper generate](#platform-helper-generate) -- [platform-helper pipeline](#platform-helper-pipeline) -- [platform-helper pipeline generate](#platform-helper-pipeline-generate) -- [platform-helper secrets](#platform-helper-secrets) -- [platform-helper secrets copy](#platform-helper-secrets-copy) -- [platform-helper secrets list](#platform-helper-secrets-list) -- [platform-helper notify](#platform-helper-notify) -- [platform-helper notify environment-progress](#platform-helper-notify-environment-progress) -- [platform-helper notify add-comment](#platform-helper-notify-add-comment) -- [platform-helper database](#platform-helper-database) -- [platform-helper database dump](#platform-helper-database-dump) -- [platform-helper database load](#platform-helper-database-load) -- [platform-helper database copy](#platform-helper-database-copy) -- [platform-helper version](#platform-helper-version) -- [platform-helper version get-platform-helper-for-project](#platform-helper-version-get-platform-helper-for-project) + - [platform-helper application](#platform-helper-application) + - [platform-helper application container-stats](#platform-helper-application-container-stats) + - [platform-helper application task-stats](#platform-helper-application-task-stats) + - [platform-helper codebase](#platform-helper-codebase) + - [platform-helper codebase prepare](#platform-helper-codebase-prepare) + - [platform-helper codebase list](#platform-helper-codebase-list) + - [platform-helper codebase build](#platform-helper-codebase-build) + - [platform-helper codebase deploy](#platform-helper-codebase-deploy) + - [platform-helper conduit](#platform-helper-conduit) + - [platform-helper config](#platform-helper-config) + - [platform-helper config validate](#platform-helper-config-validate) + - [platform-helper config aws](#platform-helper-config-aws) + - [platform-helper copilot](#platform-helper-copilot) + - [platform-helper copilot make-addons](#platform-helper-copilot-make-addons) + - [platform-helper environment](#platform-helper-environment) + - [platform-helper environment offline](#platform-helper-environment-offline) + - [platform-helper environment online](#platform-helper-environment-online) + - [platform-helper environment generate](#platform-helper-environment-generate) + - [platform-helper environment generate-terraform](#platform-helper-environment-generate-terraform) + - [platform-helper generate](#platform-helper-generate) + - [platform-helper pipeline](#platform-helper-pipeline) + - [platform-helper pipeline generate](#platform-helper-pipeline-generate) + - [platform-helper secrets](#platform-helper-secrets) + - [platform-helper secrets copy](#platform-helper-secrets-copy) + - [platform-helper secrets list](#platform-helper-secrets-list) + - [platform-helper notify](#platform-helper-notify) + - [platform-helper notify environment-progress](#platform-helper-notify-environment-progress) + - [platform-helper notify add-comment](#platform-helper-notify-add-comment) + - [platform-helper database](#platform-helper-database) + - [platform-helper database dump](#platform-helper-database-dump) + - [platform-helper database load](#platform-helper-database-load) + - [platform-helper database copy](#platform-helper-database-copy) + - [platform-helper version](#platform-helper-version) + - [platform-helper version get-platform-helper-for-project](#platform-helper-version-get-platform-helper-for-project) # platform-helper diff --git a/dbt_platform_helper/templates/COMMANDS.md.jinja b/dbt_platform_helper/templates/COMMANDS.md.jinja index a5573c8c6..71e16832d 100644 --- a/dbt_platform_helper/templates/COMMANDS.md.jinja +++ b/dbt_platform_helper/templates/COMMANDS.md.jinja @@ -1,8 +1,10 @@ # Commands Reference -{% for command in toc -%} -- [{{ command }}](#{{ command.lower() | replace(" ", "-") }}) -{% endfor %} +{% for meta in metadata -%} +{% if meta.name -%} +{{ meta.indent }}- [{{ meta.name }}](#{{ meta.name.lower() | replace(" ", "-") }}) +{% endif -%} +{% endfor -%} {%- for meta in metadata +%} {% if meta.name -%} diff --git a/tests/platform_helper/test-docs/expected_output.md b/tests/platform_helper/test-docs/expected_output.md index 44b578b3d..05717893a 100644 --- a/tests/platform_helper/test-docs/expected_output.md +++ b/tests/platform_helper/test-docs/expected_output.md @@ -1,9 +1,9 @@ # Commands Reference - [cli](#cli) -- [cli hello](#cli-hello) -- [cli argument-replacements](#cli-argument-replacements) -- [cli option-replacements](#cli-option-replacements) + - [cli hello](#cli-hello) + - [cli argument-replacements](#cli-argument-replacements) + - [cli option-replacements](#cli-option-replacements) # cli diff --git a/utils/create_command_docs.py b/utils/create_command_docs.py index 16b4e9b93..dc8bb9102 100755 --- a/utils/create_command_docs.py +++ b/utils/create_command_docs.py @@ -37,12 +37,14 @@ class CommandMetadata(NamedTuple): parent_reference: str subcommands: Optional[Any] usage: str + indent: str def get_cmd_metadata( cmd: click.core.Command, parent: Optional[click.core.Context] = None, command_name: Optional[str] = None, + indent: str = "", ) -> Generator[CommandMetadata, None, None]: """ Get command metadata recursively. @@ -100,10 +102,11 @@ def get_cmd_metadata( .split("\n"), ) ), + indent=indent, ) for sub in subcommands_names.values(): - yield from get_cmd_metadata(sub, context, command_name) + yield from get_cmd_metadata(sub, context, command_name, f"{indent} ") def create_docs(base_command, output): @@ -111,8 +114,7 @@ def create_docs(base_command, output): templates = setup_templates() content = dict( - toc=[command.name for command in get_cmd_metadata(base_command)], - metadata=get_cmd_metadata(base_command), + metadata=list(get_cmd_metadata(base_command)), ) with open(output, "w") as md_file: