From d9427c3c59882168e2bacc1cd086a1f2bc9dc213 Mon Sep 17 00:00:00 2001 From: "Vipul Gupta (@vipulgupta2048)" Date: Wed, 8 Nov 2023 20:14:32 +0530 Subject: [PATCH] Docs: Generate balenaCLI with automatic configuration Signed-off-by: Vipul Gupta (@vipulgupta2048) --- automation/build-bin.ts | 2 +- automation/capitanodoc/capitanodoc.ts | 7 +- completion/_balena | 10 +- completion/balena-completion.bash | 10 +- docs/balena-cli.md | 243 +++++--------------------- 5 files changed, 44 insertions(+), 228 deletions(-) diff --git a/automation/build-bin.ts b/automation/build-bin.ts index 69cde586..044c5709 100644 --- a/automation/build-bin.ts +++ b/automation/build-bin.ts @@ -15,7 +15,7 @@ * limitations under the License. */ -import type { JsonVersions } from '../lib/commands/version/index' +import type { JsonVersions } from '../lib/commands/version/index'; import { run as oclifRun } from '@oclif/core'; import * as archiver from 'archiver'; diff --git a/automation/capitanodoc/capitanodoc.ts b/automation/capitanodoc/capitanodoc.ts index b5cb5571..b4b4f39f 100644 --- a/automation/capitanodoc/capitanodoc.ts +++ b/automation/capitanodoc/capitanodoc.ts @@ -73,7 +73,6 @@ const allCommandsPaths = new GlobSync('build/commands/**/*.js', { }).found; // Throw error if any commands found outside of command directories -// const illegalCommandPaths = allCommandsPaths.filter((commandPath: string) => /^build\/commands\/[^/]+\.js$/.test(commandPath), ); @@ -113,18 +112,16 @@ for (const commandPath of allCommandsPaths) { categoriesMap[heading].files.push(commandPath); } -// Sort Category titles alhpabetically +// Sort Category titles alphabetically capitanoDoc.categories = capitanoDoc.categories.sort((a, b) => a.title.localeCompare(b.title), ); -// Sort Category file paths alhpabetically +// Sort Category file paths alphabetically capitanoDoc.categories.forEach((category) => { category.files.sort((a, b) => a.localeCompare(b)); }); -console.log(capitanoDoc.categories); - /** * Modify and return the `capitanoDoc` object above in order to generate the * CLI documentation at docs/balena-cli.md diff --git a/completion/_balena b/completion/_balena index d93c59c3..3a9d6b40 100644 --- a/completion/_balena +++ b/completion/_balena @@ -8,7 +8,7 @@ _balena() { local context state line curcontext="$curcontext" # Valid top-level completions - main_commands=( api-key api-keys app auth block config deploy deploy device device devices env envs fleet fleet fleets help internal key key keys local logs network notes orgs os platform preload push release release releases settings support tag tags util ) + main_commands=( api-key api-keys app auth block config deploy deploy device device devices env envs fleet fleet fleets internal key key keys local logs network notes orgs os platform preload push release release releases settings support tag tags util version ) # Sub-completions api_key_cmds=( generate revoke ) app_cmds=( create ) @@ -20,7 +20,6 @@ _balena() { devices_cmds=( supported ) env_cmds=( add rename rm ) fleet_cmds=( create pin purge rename restart rm track-latest ) - help_cmds=( version ) internal_cmds=( osinit ) key_cmds=( add rm ) local_cmds=( configure flash ) @@ -28,7 +27,6 @@ _balena() { os_cmds=( build-config configure download initialize versions ) platform_cmds=( join leave ) release_cmds=( finalize invalidate validate ) - support_cmds=( support ) tag_cmds=( rm set ) @@ -78,9 +76,6 @@ _balena_sec_cmds() { "fleet") _describe -t fleet_cmds 'fleet_cmd' fleet_cmds "$@" && ret=0 ;; - "help") - _describe -t help_cmds 'help_cmd' help_cmds "$@" && ret=0 - ;; "internal") _describe -t internal_cmds 'internal_cmd' internal_cmds "$@" && ret=0 ;; @@ -102,9 +97,6 @@ _balena_sec_cmds() { "release") _describe -t release_cmds 'release_cmd' release_cmds "$@" && ret=0 ;; - "support") - _describe -t support_cmds 'support_cmd' support_cmds "$@" && ret=0 - ;; "tag") _describe -t tag_cmds 'tag_cmd' tag_cmds "$@" && ret=0 ;; diff --git a/completion/balena-completion.bash b/completion/balena-completion.bash index b2802dcf..eee0311a 100644 --- a/completion/balena-completion.bash +++ b/completion/balena-completion.bash @@ -7,7 +7,7 @@ _balena_complete() local cur prev # Valid top-level completions - main_commands="api-key api-keys app auth block config deploy deploy device device devices env envs fleet fleet fleets help internal key key keys local logs network notes orgs os platform preload push release release releases settings support tag tags util" + main_commands="api-key api-keys app auth block config deploy deploy device device devices env envs fleet fleet fleets internal key key keys local logs network notes orgs os platform preload push release release releases settings support tag tags util version" # Sub-completions api_key_cmds="generate revoke" app_cmds="create" @@ -19,7 +19,6 @@ _balena_complete() devices_cmds="supported" env_cmds="add rename rm" fleet_cmds="create pin purge rename restart rm track-latest" - help_cmds="version" internal_cmds="osinit" key_cmds="add rm" local_cmds="configure flash" @@ -27,7 +26,6 @@ _balena_complete() os_cmds="build-config configure download initialize versions" platform_cmds="join leave" release_cmds="finalize invalidate validate" - support_cmds="support" tag_cmds="rm set" @@ -72,9 +70,6 @@ _balena_complete() fleet) COMPREPLY=( $(compgen -W "$fleet_cmds" -- $cur) ) ;; - help) - COMPREPLY=( $(compgen -W "$help_cmds" -- $cur) ) - ;; internal) COMPREPLY=( $(compgen -W "$internal_cmds" -- $cur) ) ;; @@ -96,9 +91,6 @@ _balena_complete() release) COMPREPLY=( $(compgen -W "$release_cmds" -- $cur) ) ;; - support) - COMPREPLY=( $(compgen -W "$support_cmds" -- $cur) ) - ;; tag) COMPREPLY=( $(compgen -W "$tag_cmds" -- $cur) ) ;; diff --git a/docs/balena-cli.md b/docs/balena-cli.md index 3502e1ff..4c897a7e 100644 --- a/docs/balena-cli.md +++ b/docs/balena-cli.md @@ -1,168 +1,3 @@ -[ - { - title: 'API Key', - files: [ - 'build/commands/api-key/generate.js', - 'build/commands/api-key/revoke.js' - ] - }, - { title: 'API Keys', files: [ 'build/commands/api-keys/index.js' ] }, - { title: 'App', files: [ 'build/commands/app/create.js' ] }, - { - title: 'Authentication', - files: [ - 'build/commands/auth/login.js', - 'build/commands/auth/logout.js', - 'build/commands/auth/whoami.js' - ] - }, - { title: 'Block', files: [ 'build/commands/block/create.js' ] }, - { - title: 'Config', - files: [ - 'build/commands/config/generate.js', - 'build/commands/config/inject.js', - 'build/commands/config/read.js', - 'build/commands/config/reconfigure.js', - 'build/commands/config/write.js' - ] - }, - { - title: 'Deploy', - files: [ - 'build/commands/deploy/build.js', - 'build/commands/deploy/index.js' - ] - }, - { - title: 'Device', - files: [ - 'build/commands/device/deactivate.js', - 'build/commands/device/identify.js', - 'build/commands/device/index.js', - 'build/commands/device/init.js', - 'build/commands/device/local-mode.js', - 'build/commands/device/move.js', - 'build/commands/device/os-update.js', - 'build/commands/device/pin.js', - 'build/commands/device/public-url.js', - 'build/commands/device/purge.js', - 'build/commands/device/reboot.js', - 'build/commands/device/register.js', - 'build/commands/device/rename.js', - 'build/commands/device/restart.js', - 'build/commands/device/rm.js', - 'build/commands/device/shutdown.js', - 'build/commands/device/start-service.js', - 'build/commands/device/stop-service.js', - 'build/commands/device/track-fleet.js' - ] - }, - { - title: 'Devices', - files: [ - 'build/commands/devices/index.js', - 'build/commands/devices/supported.js' - ] - }, - { - title: 'Environment Variable', - files: [ - 'build/commands/env/add.js', - 'build/commands/env/rename.js', - 'build/commands/env/rm.js' - ] - }, - { - title: 'Environment Variables', - files: [ 'build/commands/envs/index.js' ] - }, - { - title: 'Fleet', - files: [ - 'build/commands/fleet/create.js', - 'build/commands/fleet/index.js', - 'build/commands/fleet/pin.js', - 'build/commands/fleet/purge.js', - 'build/commands/fleet/rename.js', - 'build/commands/fleet/restart.js', - 'build/commands/fleet/rm.js', - 'build/commands/fleet/track-latest.js' - ] - }, - { title: 'Fleets', files: [ 'build/commands/fleets/index.js' ] }, - { - title: 'Help and Version', - files: [ 'build/commands/help/version.js' ] - }, - { - title: 'Local', - files: [ - 'build/commands/local/configure.js', - 'build/commands/local/flash.js' - ] - }, - { title: 'Logs', files: [ 'build/commands/logs/index.js' ] }, - { - title: 'Network', - files: [ - 'build/commands/network/scan.js', - 'build/commands/network/ssh.js', - 'build/commands/network/tunnel.js' - ] - }, - { title: 'Notes', files: [ 'build/commands/notes/index.js' ] }, - { title: 'Organizations', files: [ 'build/commands/orgs/index.js' ] }, - { - title: 'OS', - files: [ - 'build/commands/os/build-config.js', - 'build/commands/os/configure.js', - 'build/commands/os/download.js', - 'build/commands/os/initialize.js', - 'build/commands/os/versions.js' - ] - }, - { - title: 'Platform', - files: [ - 'build/commands/platform/join.js', - 'build/commands/platform/leave.js' - ] - }, - { title: 'Preload', files: [ 'build/commands/preload/index.js' ] }, - { title: 'Push', files: [ 'build/commands/push/index.js' ] }, - { - title: 'Release', - files: [ - 'build/commands/release/finalize.js', - 'build/commands/release/index.js', - 'build/commands/release/invalidate.js', - 'build/commands/release/validate.js' - ] - }, - { title: 'Releases', files: [ 'build/commands/releases/index.js' ] }, - { title: 'Settings', files: [ 'build/commands/settings/index.js' ] }, - { - title: 'SSH Key', - files: [ - 'build/commands/key/add.js', - 'build/commands/key/index.js', - 'build/commands/key/rm.js' - ] - }, - { title: 'SSH Keys', files: [ 'build/commands/keys/index.js' ] }, - { title: 'Support', files: [ 'build/commands/support/support.js' ] }, - { - title: 'Tag', - files: [ 'build/commands/tag/rm.js', 'build/commands/tag/set.js' ] - }, - { title: 'Tags', files: [ 'build/commands/tags/index.js' ] }, - { - title: 'Utilities', - files: [ 'build/commands/util/available-drives.js' ] - } -] # balena CLI Documentation The balena CLI is a Command Line Interface for [balenaCloud](https://www.balena.io/cloud/) or @@ -413,10 +248,6 @@ are encouraged to regularly update the balena CLI to the latest version. - [fleets](#fleets) -- Help and Version - - - [version](#version) - - Local - [local configure <target>](#local-configure-target) @@ -503,6 +334,10 @@ are encouraged to regularly update the balena CLI to the latest version. - [util available-drives](#util-available-drives) +- Version + + - [version](#version) + # API Key ## api-key generate <name> @@ -2565,41 +2400,6 @@ do not truncate output to fit screen field to sort by (prepend '-' for descending order) -# Help and Version - -## version - -Display version information for the balena CLI and/or Node.js. Note that the -balena CLI executable installers for Windows and macOS, and the standalone -zip packages, ship with a built-in copy of Node.js. In this case, the -reported version of Node.js regards this built-in copy, rather than any -other `node` engine that may also be available on the command prompt. - -The --json option is recommended when scripting the output of this command, -because the JSON format is less likely to change and it better represents -data types like lists and empty strings. The 'jq' utility may be helpful -in shell scripts (https://stedolan.github.io/jq/manual/). - -This command can also be invoked with 'balena --version' or 'balena -v'. - -Examples: - - $ balena version - $ balena version -a - $ balena version -j - $ balena --version - $ balena -v - -### Options - -#### -a, --all - -include version information for additional components (Node.js) - -#### -j, --json - -output version information in JSON format for programmatic use - # Local ## local configure <target> @@ -4025,3 +3825,38 @@ List available drives which are usable for writing an OS image to. Does not list system drives. ### Options + +# Version + +## version + +Display version information for the balena CLI and/or Node.js. Note that the +balena CLI executable installers for Windows and macOS, and the standalone +zip packages, ship with a built-in copy of Node.js. In this case, the +reported version of Node.js regards this built-in copy, rather than any +other `node` engine that may also be available on the command prompt. + +The --json option is recommended when scripting the output of this command, +because the JSON format is less likely to change and it better represents +data types like lists and empty strings. The 'jq' utility may be helpful +in shell scripts (https://stedolan.github.io/jq/manual/). + +This command can also be invoked with 'balena --version' or 'balena -v'. + +Examples: + + $ balena version + $ balena version -a + $ balena version -j + $ balena --version + $ balena -v + +### Options + +#### -a, --all + +include version information for additional components (Node.js) + +#### -j, --json + +output version information in JSON format for programmatic use