-
Notifications
You must be signed in to change notification settings - Fork 484
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Added documentation for alias command #707
Conversation
✅ Validation status: passed
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. |
## Uninstall the alias extension | ||
|
||
To uninstall the extension, use the [az extension remove](/cli/azure/extension#az-extension-remove) command. | ||
|
||
```bash | ||
```azruecli |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Typo here azruecli
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same comment as Derek. Otherwise, LGTM.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is no longer written or formatted as conceptual content.
``` | ||
|
||
To learn about the Jinja2 template engine, see [the Jinja2 documentation](http://jinja.pocoo.org/docs/2.10/templates/). | ||
|
||
### Required Parameters |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
@@ -38,7 +38,7 @@ az extension list --output table | |||
```output | |||
ExtensionType Name Version |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Change the format of this table to include the Name
column only so that the information which will frequently change can be elided.
@@ -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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Section title needs to be changed to Create new alias commands
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Change: The alias extension provides convenient and familiar commands to manage aliases.
``` | ||
[command_name] | ||
command = invoked_commands | ||
## az alias create |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
@@ -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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
``` | ||
|
||
## 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Remove note
. Do not use passive voice in conceptual documentation.
## 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Must be H2
✅ Validation status: passed
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. |
``` | ||
[command_name] | ||
command = invoked_commands | ||
```azurecli |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As convenient as the alias
command, I think there is value to keep instructions of both add through command and add through config file.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll add this section back.
@@ -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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The white space is not required anymore?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can add as many white spaces after the opening bracket and before the closing bracket
✅ Validation status: passed
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 could you please take another look at the changes? Thanks! |
✅ Validation status: passed
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. |
``` | ||
|
||
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: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"The other way"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Remove general
here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks much better, still requires some minor changes (mostly for formatting.)
@@ -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} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In some shells like zsh
, the []
token has a special meaning. Use single quotes ''
around a query.
@@ -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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
.
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pluaralize to details
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Write flags/parameters the way that they would be passed to the CLI, i.e. --help
here.
``` | ||
|
||
Don't include `az` as part of the command. | ||
## Examples |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
@@ -80,11 +76,12 @@ az rg ls | |||
az vm ls | |||
``` | |||
|
|||
Don't include az as part of the command. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 ''
.
```azurecli | ||
az alias create \ | ||
--name 'storage-ls {{ url }}' \ | ||
--command "storage blob list |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See above re: multiline commands
``` | ||
|
||
To learn about the Jinja2 template engine, see [the Jinja2 documentation](http://jinja.pocoo.org/docs/2.10/templates/). | ||
|
||
|
||
## Alias configuration file |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Include a newline after an H2.
``` | ||
|
||
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: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Remove general
here.
[command_name] | ||
command = invoked_commands | ||
``` | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Include a second example which shows how to write a command which takes arguments into the configuration file.
✅ Validation status: passed
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
[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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
✅ Validation status: passed
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 is this PR ready to be merged? |
Adding @sptramer, @derekbekoe, @twitchax, @troydai as reviewers.
With Azure/azure-cli-extensions#105 merged, I've added documentation for the new alias commands.
Alias commands file format
section and modified examples from using the alias configuration file to using alias commands. Users should usealias create
to andalias remove
to alter the configuration file since they provide additional validation on alias name and alias command.Relevant documentation:
Alias command spec