docs: updates cli reference docs (#198)

* adds files as test

* build run

* build run

* removes workflow

Author: lukegalbraithrussell

docs/reference/commands/slack.md

@@ -2,27 +2,17 @@
 
 Slack command-line tool
 
-## Synopsis
+## Description
 
 CLI to create, run, and deploy Slack apps
 
-Get started by reading the docs: [https://docs.slack.dev/tools/slack-cli](https://docs.slack.dev/tools/slack-cli/)
+Get started by reading the docs: [https://docs.slack.dev/tools/slack-cli](https://docs.slack.dev/tools/slack-cli)
 
 ```
 slack <command> <subcommand> [flags]
 ```
 
-## Examples
-
-```
-$ slack login   # Log in to your Slack account
-$ slack create  # Create a new Slack app
-$ slack init    # Initialize an existing Slack app
-$ slack run     # Start a local development server
-$ slack deploy  # Deploy to the Slack Platform
-```
-
-## Options
+## Flags
 
 ```
   -a, --app string           use a specific app ID or environment
@@ -37,7 +27,17 @@ $ slack deploy  # Deploy to the Slack Platform
   -v, --verbose              print debug logging and additional info
 ```
 
-## SEE ALSO
+## Examples
+
+```
+$ slack login   # Log in to your Slack account
+$ slack create  # Create a new Slack app
+$ slack init    # Initialize an existing Slack app
+$ slack run     # Start a local development server
+$ slack deploy  # Deploy to the Slack Platform
+```
+
+## See also
 
 * [slack activity](slack_activity)	 - Display the app activity logs from the Slack Platform
 * [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed

docs/reference/commands/slack_activity.md

@@ -2,22 +2,15 @@
 
 Display the app activity logs from the Slack Platform
 
-## Synopsis
+## Description
 
 Display the app activity logs from the Slack Platform
 
 ```
 slack activity [flags]
 ```
 
-## Examples
-
-```
-$ slack platform activity     # Display app activity logs for an app
-$ slack platform activity -t  # Continuously poll for new activity logs
-```
-
-## Options
+## Flags
 
 ```
       --component string       component type to filter
@@ -40,7 +33,7 @@ $ slack platform activity -t  # Continuously poll for new activity logs
       --trace-id string        trace id to filter
 ```
 
-## Options inherited from parent commands
+## Global flags
 
 ```
   -a, --app string           use a specific app ID or environment
@@ -54,7 +47,14 @@ $ slack platform activity -t  # Continuously poll for new activity logs
   -v, --verbose              print debug logging and additional info
 ```
 
-## SEE ALSO
+## Examples
+
+```
+$ slack platform activity     # Display app activity logs for an app
+$ slack platform activity -t  # Continuously poll for new activity logs
+```
+
+## See also
 
 * [slack](slack)	 - Slack command-line tool
 

docs/reference/commands/slack_app.md

@@ -2,32 +2,21 @@
 
 Install, uninstall, and list teams with the app installed
 
-## Synopsis
+## Description
 
 Install, uninstall, and list teams with the app installed
 
 ```
 slack app [flags]
 ```
 
-## Examples
-
-```
-$ slack app install    # Install a production app to a team
-$ slack app link       # Link an existing app to the project
-$ slack app list       # List all teams with the app installed
-$ slack app settings   # Open app settings in a web browser
-$ slack app uninstall  # Uninstall an app from a team
-$ slack app delete     # Delete an app and app info from a team
-```
-
-## Options
+## Flags
 
 ```
   -h, --help   help for app
 ```
 
-## Options inherited from parent commands
+## Global flags
 
 ```
   -a, --app string           use a specific app ID or environment
@@ -41,7 +30,18 @@ $ slack app delete     # Delete an app and app info from a team
   -v, --verbose              print debug logging and additional info
 ```
 
-## SEE ALSO
+## Examples
+
+```
+$ slack app install    # Install a production app to a team
+$ slack app link       # Link an existing app to the project
+$ slack app list       # List all teams with the app installed
+$ slack app settings   # Open app settings in a web browser
+$ slack app uninstall  # Uninstall an app from a team
+$ slack app delete     # Delete an app and app info from a team
+```
+
+## See also
 
 * [slack](slack)	 - Slack command-line tool
 * [slack app delete](slack_app_delete)	 - Delete the app

docs/reference/commands/slack_app_delete.md

@@ -2,31 +2,21 @@
 
 Delete the app
 
-## Synopsis
+## Description
 
 Uninstall the app from the team and permanently delete the app and all of its data
 
 ```
 slack app delete [flags]
 ```
 
-## Examples
-
-```
-# Delete an app and app info from a team
-$ slack app delete
-
-# Delete a specific app from a team
-$ slack app delete --team T0123456 --app local
-```
-
-## Options
+## Flags
 
 ```
   -h, --help   help for delete
 ```
 
-## Options inherited from parent commands
+## Global flags
 
 ```
   -a, --app string           use a specific app ID or environment
@@ -40,7 +30,17 @@ $ slack app delete --team T0123456 --app local
   -v, --verbose              print debug logging and additional info
 ```
 
-## SEE ALSO
+## Examples
+
+```
+# Delete an app and app info from a team
+$ slack app delete
+
+# Delete a specific app from a team
+$ slack app delete --team T0123456 --app local
+```
+
+## See also
 
 * [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_install.md

@@ -2,32 +2,24 @@
 
 Install the app to a team
 
-## Synopsis
+## Description
 
 Install the app to a team
 
 ```
 slack app install [flags]
 ```
 
-## Examples
-
-```
-$ slack app install                  # Install a production app to a team
-
-# Install a production app to a specific team
-$ slack app install --team T0123456
-```
-
-## Options
+## Flags
 
 ```
+  -E, --environment string           environment of app (local, deployed)
   -h, --help                         help for install
       --org-workspace-grant string   grant access to a specific org workspace ID
                                        (or 'all' for all workspaces in the org)
 ```
 
-## Options inherited from parent commands
+## Global flags
 
 ```
   -a, --app string           use a specific app ID or environment
@@ -41,7 +33,20 @@ $ slack app install --team T0123456
   -v, --verbose              print debug logging and additional info
 ```
 
-## SEE ALSO
+## Examples
+
+```
+# Install a production app to a team
+$ slack app install
+
+# Install a production app to a specific team
+$ slack app install --team T0123456 --environment deployed
+
+# Install a local dev app to a specific team
+$ slack app install --team T0123456 --environment local
+```
+
+## See also
 
 * [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_link.md

@@ -2,7 +2,7 @@
 
 Add an existing app to the project
 
-## Synopsis
+## Description
 
 Saves an existing app to a project to be available to other commands.
 
@@ -19,24 +19,14 @@ Only one app can exist for each combination of Team ID and environment.
 slack app link [flags]
 ```
 
-## Examples
-
-```
-# Add an existing app to a project
-$ slack app link
-
-# Add a specific app without using prompts
-$ slack app link --team T0123456789 --app A0123456789 --environment deployed
-```
-
-## Options
+## Flags
 
 ```
   -E, --environment string   environment to save existing app (local, deployed)
   -h, --help                 help for link
 ```
 
-## Options inherited from parent commands
+## Global flags
 
 ```
   -a, --app string           use a specific app ID or environment
@@ -50,7 +40,17 @@ $ slack app link --team T0123456789 --app A0123456789 --environment deployed
   -v, --verbose              print debug logging and additional info
 ```
 
-## SEE ALSO
+## Examples
+
+```
+# Add an existing app to a project
+$ slack app link
+
+# Add a specific app without using prompts
+$ slack app link --team T0123456789 --app A0123456789 --environment deployed
+```
+
+## See also
 
 * [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed
 

docs/reference/commands/slack_app_list.md

@@ -2,29 +2,23 @@
 
 List teams with the app installed
 
-## Synopsis
+## Description
 
 List all teams that have installed the app
 
 ```
 slack app list [flags]
 ```
 
-## Examples
-
-```
-$ slack app list  # List all teams with the app installed
-```
-
-## Options
+## Flags
 
 ```
       --all-org-workspace-grants   display all workspace grants for an app
                                    installed to an organization
   -h, --help                       help for list
 ```
 
-## Options inherited from parent commands
+## Global flags
 
 ```
   -a, --app string           use a specific app ID or environment
@@ -38,7 +32,13 @@ $ slack app list  # List all teams with the app installed
   -v, --verbose              print debug logging and additional info
 ```
 
-## SEE ALSO
+## Examples
+
+```
+$ slack app list  # List all teams with the app installed
+```
+
+## See also
 
 * [slack app](slack_app)	 - Install, uninstall, and list teams with the app installed