Skip to content
Merged
Changes from 6 commits
Commits
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
28 changes: 8 additions & 20 deletions doc/authoring_command_modules/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,39 +28,23 @@ For example:
```
git clone https://github.com/Azure/azure-cli.git
cd azure-cli
virtualenv env
python -m venv env
source env/bin/activate

Copy link
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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 with `az`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
If your command module contributes any commands, they should appear with `az`.
If your command module contributes any commands, they should appear when running `az`.

Make it more clear with a verb.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

done

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The example_module_template directory no longer exists, right? This line can also be removed.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

yes


Command modules should have the following structure:
Expand All @@ -79,6 +63,10 @@ Command modules should have the following structure:
`-- HISTORY.rst
```

You could create these files manually, or [create a module with `azdev cli create`](https://azurecliprod.blob.core.windows.net/videos/04%20-%20AzdevCliCreate.mp4).

You could also consider using [Code-gen tool](https://azurecliprod.blob.core.windows.net/videos/04%20-%20AzdevCliCreate.mp4) to generate code automatically.

@fengzhou-msft fengzhou-msft Mar 12, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The link is not right for Code-gen.

Shall we move Code-gen above azdev cli create as it is more recommended now?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

good check!


Comment thread
Juliehzl marked this conversation as resolved.
**Create an \_\_init__.py for your module**

In the \_\_init__ file, you will declare a command loader class that inherits from AzCommandsLoader. You will typically override the following three methods:
Expand Down