Added documentation for alias command #707

chewong · 2018-03-30T20:36:08Z

Adding @sptramer, @derekbekoe, @twitchax, @troydai as reviewers.

With Azure/azure-cli-extensions#105 merged, I've added documentation for the new alias commands.

Deleted Alias commands file format section and modified examples from using the alias configuration file to using alias commands. Users should use alias create to and alias remove to alter the configuration file since they provide additional validation on alias name and alias command.

Relevant documentation:
Alias command spec

formulahendry · 2018-03-30T20:39:00Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs-ref-conceptual/azure-cli-extension-alias.md	✅Succeeded	View (azure-cli-latest) View (azure-cli-2017-03-09-profile)
docs-ref-conceptual/azure-cli-extensions-list.md	✅Succeeded	View (azure-cli-latest) View (azure-cli-2017-03-09-profile)

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

derekbekoe · 2018-03-30T20:40:24Z

docs-ref-conceptual/azure-cli-extension-alias.md

 ## Uninstall the alias extension

 To uninstall the extension, use the [az extension remove](/cli/azure/extension#az-extension-remove) command.

-```bash
+```azruecli


Typo here azruecli

twitchax

Same comment as Derek. Otherwise, LGTM.

sptramer

This is no longer written or formatted as conceptual content.

sptramer · 2018-03-30T21:10:41Z

docs-ref-conceptual/azure-cli-extension-alias.md

 ```

 To learn about the Jinja2 template engine, see [the Jinja2 documentation](http://jinja.pocoo.org/docs/2.10/templates/).

+### Required Parameters


This is reference documentation and should be removed. We don't have any current place for reference documentation on the site, however. Conceptual docs should instead reference the -h argument.

sptramer · 2018-03-30T21:11:24Z

docs-ref-conceptual/azure-cli-extension-alias.md

@@ -38,7 +38,7 @@ az extension list --output table
 ```output
 ExtensionType    Name                       Version


Change the format of this table to include the Name column only so that the information which will frequently change can be elided.

sptramer · 2018-03-30T21:17:49Z

docs-ref-conceptual/azure-cli-extension-alias.md

@@ -49,27 +49,28 @@ The alias extension is under active development and new versions are released re
 az extension update --name alias
 ```

-## Alias commands file format
+## az alias


Section title needs to be changed to Create new alias commands

sptramer · 2018-03-30T21:18:08Z

docs-ref-conceptual/azure-cli-extension-alias.md


-Alias command definitions are written into a configuration file, located at `$AZURE_USER_CONFIG/alias`. The default value of `AZURE_USER_CONFIG` is `$HOME/.azure` on macOS and Linux, and `%USERPROFILE%\.azure` on Windows. The alias configuration file is written in the INI configuration file format. The general format for alias commands is:
+Alias provides convenient and familiar commands to manage your aliases.


Change: The alias extension provides convenient and familiar commands to manage aliases.

sptramer · 2018-03-30T21:18:58Z

docs-ref-conceptual/azure-cli-extension-alias.md

-```
-[command_name]
-command = invoked_commands
+## az alias create


Remove entire section. The process of creating an alias should be described in plain language, as non-reference material, detailing the usage of the command's --name and --command parameters.

sptramer · 2018-03-30T21:20:04Z

docs-ref-conceptual/azure-cli-extension-alias.md

@@ -93,20 +93,21 @@ Now `ls-groups` can be run like any other CLI command.
 az ls-groups
 ```

-## Create an alias command with arguments
+### Create an alias command with arguments


This must not be an H3 level title. All titles in this document must be at the H2 level for scannability. This is not reference material.

sptramer · 2018-03-30T21:20:35Z

docs-ref-conceptual/azure-cli-extension-alias.md

 ```

-## Process arguments using Jinja2 templates
+Note that you will have to escape the dollar sign `$` by adding a slash `\` in order to register the environment variables inside the command of the alias.


Remove note. Do not use passive voice in conceptual documentation.

sptramer · 2018-03-30T21:20:48Z

docs-ref-conceptual/azure-cli-extension-alias.md

-## Process arguments using Jinja2 templates
+Note that you will have to escape the dollar sign `$` by adding a slash `\` in order to register the environment variables inside the command of the alias.
+
+### Process arguments using Jinja2 templates


formulahendry · 2018-03-30T22:29:07Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs-ref-conceptual/azure-cli-extension-alias.md	✅Succeeded	View (azure-cli-latest) View (azure-cli-2017-03-09-profile)

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

troydai · 2018-04-03T23:16:20Z

docs-ref-conceptual/azure-cli-extension-alias.md

-```
-[command_name]
-command = invoked_commands
+```azurecli


As convenient as the alias command, I think there is value to keep instructions of both add through command and add through config file.

I'll add this section back.

troydai · 2018-04-03T23:17:01Z

docs-ref-conceptual/azure-cli-extension-alias.md

@@ -95,51 +92,59 @@ az ls-groups

 ## Create an alias command with arguments

-You can also add positional arguments to an alias command by including them as `{{ arg_name }}` in the alias name. The whitespace inside the curly braces is required.
+You can also add positional arguments to an alias command by including them as `{{ arg_name }}` in the alias name.


The white space is not required anymore?

You can add as many white spaces after the opening bracket and before the closing bracket

formulahendry · 2018-04-04T16:48:00Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs-ref-conceptual/azure-cli-extension-alias.md	✅Succeeded	View (azure-cli-latest) View (azure-cli-2017-03-09-profile)

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

chewong · 2018-04-04T21:28:05Z

@sptramer could you please take another look at the changes? Thanks!

formulahendry · 2018-04-04T21:29:04Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs-ref-conceptual/azure-cli-extension-alias.md	✅Succeeded	View (azure-cli-latest) View (azure-cli-2017-03-09-profile)

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

troydai · 2018-04-05T21:46:43Z

docs-ref-conceptual/azure-cli-extension-alias.md

 ```

 To learn about the Jinja2 template engine, see [the Jinja2 documentation](http://jinja.pocoo.org/docs/2.10/templates/).

+
+## Alias configuration file
+Another way to create and modify aliaes is to alter the alias configuration file. Alias command definitions are written into a configuration file, located at `$AZURE_USER_CONFIG/alias`. The default value of `AZURE_USER_CONFIG` is `$HOME/.azure` on macOS and Linux, and `%USERPROFILE%\.azure` on Windows. The alias configuration file is written in the INI configuration file format. The general format for alias commands is:


"The other way"

Remove general here.

sptramer

Looks much better, still requires some minor changes (mostly for formatting.)

sptramer · 2018-04-07T00:22:18Z

docs-ref-conceptual/azure-cli-extension-alias.md

@@ -32,13 +32,13 @@ az extension add --name alias
 Verify the installation of the extension with [az extension list](/cli/azure/extension#az-extension-list). If the alias extension was installed properly, it's listed in the command output.

 ```azurecli
-az extension list --output table
+az extension list --output table --query [].{Name:name}


In some shells like zsh, the [] token has a special meaning. Use single quotes '' around a query.

sptramer · 2018-04-07T00:28:21Z

docs-ref-conceptual/azure-cli-extension-alias.md

@@ -49,27 +49,23 @@ The alias extension is under active development and new versions are released re
 az extension update --name alias
 ```

-## Alias commands file format
+## Manager Azure CLI aliases


The first word of H2 sections in our documentation should generally be an imperative verb, so the reader sees it as a call to action. This H2 should read something like Manage aliases for the Azure CLI.

sptramer · 2018-04-07T00:28:49Z

docs-ref-conceptual/azure-cli-extension-alias.md


-Alias command definitions are written into a configuration file, located at `$AZURE_USER_CONFIG/alias`. The default value of `AZURE_USER_CONFIG` is `$HOME/.azure` on macOS and Linux, and `%USERPROFILE%\.azure` on Windows. The alias configuration file is written in the INI configuration file format. The general format for alias commands is:
+The alias extension provides convenient and familiar commands to manage aliases. To view all the available commands and parameter detail, invoke the alias command with the help flag.


Pluaralize to details

Write flags/parameters the way that they would be passed to the CLI, i.e. --help here.

sptramer · 2018-04-07T00:33:11Z

docs-ref-conceptual/azure-cli-extension-alias.md

 ```

-Don't include `az` as part of the command.
+## Examples


Remove this H2. H2s in our docs are always fully fleshed out sections that are designed to be easy to find and navigate to from the right-hand ToC. Users are more likely to look for a specific type of example rather than just any example.

sptramer · 2018-04-07T00:35:43Z

docs-ref-conceptual/azure-cli-extension-alias.md

@@ -80,11 +76,12 @@ az rg ls
 az vm ls
 ```

+Don't include az as part of the command.


Place az in preformat quotes `` so that it's clear that it's something users would type as part of a command. CLI commands are always written in backticks unless they are a link out to reference documentation.

sptramer · 2018-04-07T00:45:37Z

docs-ref-conceptual/azure-cli-extension-alias.md

-command = group create --name {{ groupName }} --location eastus --tags owner=$USER
-```
+
+To register the environment variables inside the command of the alias, the dollar sign `$` needs to be escaped by adding a slash `\` in front of it.


Leave out the instructions on how to escape the $ token, and just leave it as the variable must be escaped. This is important since shell escape is only needed inside "" strings and users may write them as ''.

sptramer · 2018-04-07T00:48:26Z

docs-ref-conceptual/azure-cli-extension-alias.md

+```azurecli
+az alias create \
+    --name 'storage-ls {{ url }}' \
+    --command "storage blob list


See above re: multiline commands

sptramer · 2018-04-07T00:48:50Z

docs-ref-conceptual/azure-cli-extension-alias.md

 ```

 To learn about the Jinja2 template engine, see [the Jinja2 documentation](http://jinja.pocoo.org/docs/2.10/templates/).

+
+## Alias configuration file


Include a newline after an H2.

sptramer · 2018-04-07T00:50:28Z

docs-ref-conceptual/azure-cli-extension-alias.md

 ```

 To learn about the Jinja2 template engine, see [the Jinja2 documentation](http://jinja.pocoo.org/docs/2.10/templates/).

+
+## Alias configuration file
+Another way to create and modify aliaes is to alter the alias configuration file. Alias command definitions are written into a configuration file, located at `$AZURE_USER_CONFIG/alias`. The default value of `AZURE_USER_CONFIG` is `$HOME/.azure` on macOS and Linux, and `%USERPROFILE%\.azure` on Windows. The alias configuration file is written in the INI configuration file format. The general format for alias commands is:


Remove general here.

sptramer · 2018-04-07T00:50:51Z

docs-ref-conceptual/azure-cli-extension-alias.md

+[command_name]
+command = invoked_commands
+```
+


Include a second example which shows how to write a command which takes arguments into the configuration file.

formulahendry · 2018-04-09T17:31:43Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs-ref-conceptual/azure-cli-extension-alias.md	✅Succeeded	View (azure-cli-latest) View (azure-cli-2017-03-09-profile)

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

sptramer

Looking much better, thanks for the work that you've put in. I have one optional comment left that you can address, or I can add it in later.

sptramer · 2018-04-09T18:38:56Z

docs-ref-conceptual/azure-cli-extension-alias.md

-[ls-groups]
-command = group list --query '[].{Name:name, Location:location}' --output table
+```azurecli
+az alias create --name ls-groups --command "group list --query '[].{Name:name, Location:location}' --output table"
 ```

 Now `ls-groups` can be run like any other CLI command.


I would include a line around here that lets users know that the value passed to --command must not contain newlines. This makes it clearer why all of the following examples don't span multiple lines, and will prevent a common user mistake.

Alias would attempt to convert all excessive whitespaces and next line character \n to single whitespaces. So technically it is valid for users to pass in commands that span multiple lines, but the actual value that we store in the configuration file would be the whitespace-truncated string. Should I still include warning?

No, that's fine. In this case, can you put the newlines back into the examples they were removed from to make them more readable? The only reason I suggested removing them was that I wasn't sure if there was whitespace-stripping performed by the alias extension before writing to the config file.

formulahendry · 2018-04-09T20:10:48Z

✅ Validation status: passed

File	Status	Preview URL	Details
docs-ref-conceptual/azure-cli-extension-alias.md	✅Succeeded	View (azure-cli-latest) View (azure-cli-2017-03-09-profile)

For more details, please refer to the build report.

Note: If you changed an existing file name or deleted a file, broken links in other files to the deleted or renamed file are listed only in the full build report.

chewong · 2018-04-10T18:18:48Z

@sptramer is this PR ready to be merged?

derekbekoe reviewed Mar 30, 2018

View reviewed changes

twitchax approved these changes Mar 30, 2018

View reviewed changes

sptramer suggested changes Mar 30, 2018

View reviewed changes

troydai suggested changes Apr 3, 2018

View reviewed changes

Ernest Wong added 3 commits April 4, 2018 14:25

Add alias commands

f6da949

Address PR comments

cf1b958

Add 'Alias configuration file' section

4f3348e

troydai approved these changes Apr 5, 2018

View reviewed changes

sptramer suggested changes Apr 7, 2018

View reviewed changes

Address PR comments

6fac8d9

sptramer reviewed Apr 9, 2018

View reviewed changes

sptramer approved these changes Apr 9, 2018

View reviewed changes

Address PR comments

fb89dcf

sptramer merged commit 3374a70 into MicrosoftDocs:master Apr 10, 2018

chewong deleted the alias-0.3.0 branch April 10, 2018 18:40

		@@ -38,7 +38,7 @@ az extension list --output table
		```output
		ExtensionType Name Version


		Alias command definitions are written into a configuration file, located at `$AZURE_USER_CONFIG/alias`. The default value of `AZURE_USER_CONFIG` is `$HOME/.azure` on macOS and Linux, and `%USERPROFILE%\.azure` on Windows. The alias configuration file is written in the INI configuration file format. The general format for alias commands is:
		Alias provides convenient and familiar commands to manage your aliases.


		Alias command definitions are written into a configuration file, located at `$AZURE_USER_CONFIG/alias`. The default value of `AZURE_USER_CONFIG` is `$HOME/.azure` on macOS and Linux, and `%USERPROFILE%\.azure` on Windows. The alias configuration file is written in the INI configuration file format. The general format for alias commands is:
		The alias extension provides convenient and familiar commands to manage aliases. To view all the available commands and parameter detail, invoke the alias command with the help flag.

Added documentation for alias command #707

Added documentation for alias command #707

Conversation

chewong commented Mar 30, 2018

formulahendry commented Mar 30, 2018

✅ Validation status: passed

Choose a reason for hiding this comment

twitchax left a comment

Choose a reason for hiding this comment

sptramer left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

formulahendry commented Mar 30, 2018

✅ Validation status: passed

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

formulahendry commented Apr 4, 2018

✅ Validation status: passed

chewong commented Apr 4, 2018

formulahendry commented Apr 4, 2018

✅ Validation status: passed

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sptramer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

formulahendry commented Apr 9, 2018

✅ Validation status: passed

sptramer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

formulahendry commented Apr 9, 2018

✅ Validation status: passed

chewong commented Apr 10, 2018

sptramer left a comment •

edited

Loading