add generated cli page to docs

dlt-hub · Jan 24, 2025 · 2da6506 · 2da6506
1 parent 7212a32
commit 2da6506
Show file tree

Hide file tree

Showing 7 changed files with 30 additions and 14 deletions.
diff --git a/dlt/cli/_dlt.py b/dlt/cli/_dlt.py
@@ -128,15 +128,15 @@ def _create_parser() -> Tuple[argparse.ArgumentParser, Dict[str, SupportsCliComm
     parser.add_argument(
         "--debug", action=DebugAction, help="Displays full stack traces on exceptions."
     )
-    subparsers = parser.add_subparsers(title="Available Commands", dest="command")
+    subparsers = parser.add_subparsers(title="Available subcommands", dest="command")
 
     # load plugins
     from dlt.common.configuration import plugins
 
     m = plugins.manager()
     commands = cast(List[Type[SupportsCliCommand]], m.hook.plug_cli())
 
-    # install available commands
+    # install Available subcommands
     installed_commands: Dict[str, SupportsCliCommand] = {}
     for c in commands:
         command = c()

diff --git a/dlt/cli/docs_command.py b/dlt/cli/docs_command.py
@@ -5,7 +5,7 @@
 import os
 
 HEADER = """---
-title: Command line interface
+title: Full CLI Reference
 description: Command line interface (CLI) of dlt
 keywords: [command line interface, cli, dlt init]
 ---
@@ -72,7 +72,7 @@ def _text_wrap_line(line: str, indent: int = 4) -> str:
         usage = _text_wrap_line(usage)
 
         # get description or use help passed down from choices
-        description = parser.description or help or ""
+        description = parser.description or help_string or ""
 
         # extract all other sections
         extracted_sections = []

diff --git a/dlt/cli/plugins.py b/dlt/cli/plugins.py
@@ -141,7 +141,7 @@ def configure_parser(self, pipe_cmd: argparse.ArgumentParser) -> None:
         )
 
         pipeline_subparsers = pipe_cmd.add_subparsers(
-            title="Available Commands", dest="operation", required=False
+            title="Available subcommands", dest="operation", required=False
         )
 
         pipe_cmd_sync_parent = argparse.ArgumentParser(add_help=False)
@@ -333,7 +333,7 @@ def configure_parser(self, parser: argparse.ArgumentParser) -> None:
         )
 
         deploy_sub_parsers = deploy_cmd.add_subparsers(
-            title="Available Commands", dest="deployment_method"
+            title="Available subcommands", dest="deployment_method"
         )
 
         # deploy github actions

diff --git a/docs/tools/README.md b/docs/tools/README.md
@@ -25,7 +25,7 @@ This script is run on CI to ensure code quality in our docs.
 # Run a full check on all snippets
 python check_embedded_snippets.py full
 
-# Show all available commands and arguments for this script
+# Show all Available subcommands and arguments for this script
 python check_embedded_snippets.py --help
 
 # Only run the linting stage

diff --git a/docs/website/docs/reference/.gitignore b/docs/website/docs/reference/.gitignore
@@ -0,0 +1 @@
+/command-line-interface-generated.md
diff --git a/docs/website/package.json b/docs/website/package.json
@@ -4,18 +4,23 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
-    "start": "PYTHONPATH=. poetry run pydoc-markdown && node tools/preprocess_docs.js && concurrently --kill-others \"node tools/preprocess_docs.js --watch\" \"docusaurus start\"",
-    "build": "node tools/update_versions.js && node tools/preprocess_docs.js && PYTHONPATH=. poetry run pydoc-markdown && docusaurus build",
-    "build:netlify": "node tools/update_versions.js && node tools/preprocess_docs.js && PYTHONPATH=. pydoc-markdown && docusaurus build --out-dir build/docs",
+    "start": "npm run preprocess_docs && npm run gen-api-ref && npm run render-cli-docs && concurrently --kill-others \"node tools/preprocess_docs.js --watch\" \"docusaurus start\"",
+    "build": "npm run update-versions && npm run preprocess-docs && npm run gen-api-ref && npm run render-cli-docs && docusaurus build",
+    "build:netlify": "npm run update-versions && npm run preprocess-docs && npm run gen-api-ref-netlify && npm run render-cli-docs && docusaurus build --out-dir build/docs",
     "swizzle": "docusaurus swizzle",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "preprocess-docs": "node tools/preprocess_docs.js",
-    "generate-api-reference": "PYTHONPATH=. poetry run pydoc-markdown",
+
     "clear-versions": "node tools/clear_versions.js",
-    "update-versions": "node tools/update_versions.js"
+    "update-versions": "node tools/update_versions.js",
+
+    "run-preprocessing-steps": "npm run preprocess-docs && npm run gen-api-ref && npm run render-cli-docs",
+    "preprocess-docs": "node tools/preprocess_docs.js",
+    "gen-api-ref": "PYTHONPATH=. poetry run pydoc-markdown",
+    "gen-api-ref-netlify": "PYTHONPATH=. pydoc-markdown",
+    "render-cli-docs": "PYTHONPATH=. poetry run dlt render-docs > docs/reference/command-line-interface-generated.md"
   },
   "dependencies": {
     "@docusaurus/core": "2.4.3",

diff --git a/docs/website/sidebars.js b/docs/website/sidebars.js
@@ -343,7 +343,17 @@ const sidebars = {
         keywords: ['reference'],
       },
       items: [
-        'reference/command-line-interface',
+        {
+          type: 'category',
+          label: 'Command Line Interface',
+          link: {
+            type: 'doc',
+            id: 'reference/command-line-interface',
+          },
+          items: [
+            'reference/command-line-interface-generated',
+          ]
+        },
         'reference/telemetry',
         // Unsure item
         'general-usage/destination-tables',