Skip to content
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.

Sign up for GitHub

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

{doc} Refine authoring commands doc #17236

Merged
merged 10 commits into from
Apr 12, 2021
Merged

{doc} Refine authoring commands doc #17236

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
b6cd683
update setup
Juliehzl Mar 9, 2021
b57f13e
refine init
Juliehzl Mar 9, 2021
852e6db
refine
Juliehzl Mar 9, 2021
a857a2c
Update doc/authoring_command_modules/README.md
Juliehzl Mar 11, 2021
46e05fa
Update doc/authoring_command_modules/README.md
Juliehzl Mar 11, 2021
e95c822
Update doc/authoring_command_modules/README.md
Juliehzl Mar 11, 2021
3cbd7e8
fix comments
Juliehzl Apr 9, 2021
97f87e7
fix link
Juliehzl Apr 9, 2021
cadc64e
fix typo
Juliehzl Apr 9, 2021
ee902f9
fix workflow
Juliehzl Apr 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 10 additions & 39 deletions doc/authoring_command_modules/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,64 +20,35 @@ The document provides instructions and guidelines on how to author command modul
<a name="heading_set_up"></a>Set Up
------

Create you dev environment if you haven't already. This is how to do that.
Create your dev environment if you haven't already. This is how to do that.

Clone the repo, enter the repo directory then create your virtual environment.

For example:
```
git clone https://github.com/Azure/azure-cli.git
cd azure-cli
virtualenv env
git clone https://github.com/Azure/azure-cli-extensions.git
python -m venv env
source env/bin/activate
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You assume it is Linux environment.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. It is a simple example and for more information about setting up environment, link to https://github.com/Azure/azure-cli-dev-tools#setting-up-your-development-environment for details.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add a hint "This is script for Linux"?

python scripts/dev_setup.py
azdev setup -c azure-cli -r azure-cli-extensions
```
For more information, see https://github.com/Azure/azure-cli-dev-tools#setting-up-your-development-environment.

After this, you should be able to run the CLI with `az`.

[Author your command module...](#heading_author_command_mod)

Now, install your command module into the environment with pip in editable mode.
Where `<path_to_your_command_module>` is the path to the directory containing your `setup.py` file.
```
pip install -e <path_to_your_command_module>
```

If installation was successful, you should be able to run `pip list` and see your command module.
```
$ pip list
...
azure-cli-example (0.0.1, /Users/myuser/Repos/azure-cli-example)
...
```

Also, you can run `az` and if your command module contributes any commands, they should appear.
If your command module contributes any commands, they should appear when running `az`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is "they"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

commands

If your commands aren't showing with `az`, use `az --debug` to help debug. There could have been an exception
thrown whilst attempting to load your module.


<a name="heading_author_command_mod"></a>Authoring command modules
------
Currently, all command modules should start with `azure-cli-`.
When the CLI loads, it search for packages installed that start with that prefix.

The `example_module_template` directory gives an example command module with other useful examples.

Command modules should have the following structure:
```
.
|-- README.rst
|-- azure
| |-- __init__.py
| `-- cli
| |-- __init__.py
| `-- command_modules
| |-- __init__.py
| `-- <MODULE_NAME>
| `-- __init__.py
`-- setup.py
`-- HISTORY.rst
```

There are two options to initialize a command module:
1. Use [Azure CLI Code Generator tool](https://github.com/Azure/autorest.az#how-does-azure-cli-code-generator-work) to generate code automatically.
2. [Create a module with `azdev cli create`](https://azurecliprod.blob.core.windows.net/videos/04%20-%20AzdevCliCreate.mp4).

**Create an \_\_init__.py for your module**

Expand Down