complete first help doc draft

Author: DannyBen

lib/bashly/docs/command.yml

@@ -51,7 +51,7 @@ command.catch_all:
     - name: download
       help: Download one or more URLs
       
-      # Set to true to simply enable this option
+      # Set to 'true' to simply enable this option
       catch_all: true
 
     - name: upload
@@ -149,6 +149,82 @@ command.examples:
       Upload a file (you will be prompted to provide a password)
       $ cli upload profile.png --user admin
 
+command.expose:
+  help: Specify that the sub-commands of this command should be visible when showing the usage of its parent.
+  url: https://bashly.dannyb.co/configuration/command/#expose
+  example: |-
+    name: cli
+    commands:
+    - name: config
+      help: Config management commands
+
+      # Set to 'true' to show both 'config edit' and 'config show' when
+      # running 'cli --help'
+      expose: true
+      commands:
+      - name: edit
+        help: Edit config file
+      - name: show
+        help: Show config file
+
+    - name: server
+      help: Server management commands
+      
+      # Set to 'always' to also show the usage of the sub-commands when
+      # running 'cli' without arguments.
+      expose: always
+
+      commands:
+      - name: start
+        help: Start the server
+      - name: stop
+        help: Stop the server
+
+command.extensible:
+  help: Specify that this command can be extended by external means.
+  url: https://bashly.dannyb.co/configuration/command/#extensible
+  example: |-
+    name: mygit
+    help: Wrapper for git
+    version: 0.1.0
+
+    # Set to 'true' to allow extending it by creating executables in the
+    # path named 'mygit-*'.
+    extensible: true
+
+    # Set to another executable name to delegate all unknown commands
+    # to it.
+    extensible: git
+
+command.filename:
+  help: Specify the path (relative to src) to the partial source code file.
+  url: https://bashly.dannyb.co/configuration/command/#filename
+  example: |-
+    commands:
+    - name: connect
+      help: Connect to server
+      filename: admin_commands/list.sh
+
+command.filters:
+  help: Specify a list of custom filter functions that will prevent the command from running unless certain conditions are met.
+  url: https://bashly.dannyb.co/configuration/command/#filters
+  example: |-
+    commands:
+    - name: container
+      help: Perform actions on a docker container
+
+      # When the command is executed, your script will look for a function
+      # named 'filter_docker_running' and execute it. If it prints a string,
+      # it will be considered an error and the command execution will be
+      # halted.
+      filters:
+      - docker_running
+
+    # Example function (put somewhere in src/lib)
+    filter_docker_running() {
+      docker info >/dev/null 2>&1 || echo "Docker must be running"
+    }
+
 command.flags:
   help: Define a list of option flags. See `flag` for reference.
   url: https://bashly.dannyb.co/configuration/command/#flags
@@ -164,6 +240,27 @@ command.footer:
   example: |-
     footer: For further help visit https://my.docs-site.com
 
+command.function:
+  help: Specify a different base function name for this command.
+  url: https://bashly.dannyb.co/configuration/command/#function
+  example: |-
+    commands:
+    - name: container-start
+      help: Start a new container (deprecated)
+
+      # Override the name of the internal functions bashly uses. This is
+      # needed in this case since the command 'container-start' and the
+      # nested command 'container start' will have the same underlying
+      # function name otherwise.
+      function: deprecated_container_start
+      footer: This command is deprecated, use 'container start' instead
+
+    - name: container
+      help: Container commands
+      commands:
+      - name: start
+        help: Start a new container
+
 command.group:
   help: Specify the group that this command belongs to.
   url: https://bashly.dannyb.co/configuration/command/#group
@@ -195,6 +292,15 @@ command.name:
     - name: images
       help: Manage images
 
+command.private:
+  help: Specify that this command should not be displayed in the help text.
+  url: https://bashly.dannyb.co/configuration/command/#private
+  example: |-
+    commands:
+    - name: completions
+      help: Send bash completions
+      private: true
+
 command.version:
   help: Specify the version to show when running with `--version`.
   url: https://bashly.dannyb.co/configuration/command/#version

lib/bashly/docs/env.yml

@@ -35,6 +35,16 @@ environment_variable.name:
     - name: api_key
       help: Your API key
 
+environment_variable.private:
+  help: Specify that this environment variable should not be advertised in the usage text. Only makes sense when accompanied by `default`.
+  url: https://bashly.dannyb.co/configuration/environment-variable/#private
+  example: |-
+    environment_variables:
+    - name: editor
+      help: Editor to use
+      default: vim
+      private: true
+
 environment_variable.required:
   help: Specify that this variable is required.
   url: https://bashly.dannyb.co/configuration/environment-variable/#required