Azure · AllyW · Jul 28, 2022 · Jul 27, 2022 · Jul 27, 2022 · Jul 27, 2022
diff --git a/README.md b/README.md
@@ -102,6 +102,14 @@ pip install azdev
     ```bash
     pip install $(curl https://api.github.com/repos/Azure/aaz-dev-tools/releases/latest -s | grep -o "https.*.whl")
     ```
+#### 4.3 Set up build env
+- For linux users, set up python3 build tools would avoid other unseen installation issues
+  ```
+  Ubuntu: apt-get install python3-dev build-essential
+  Centos: yum install python3-devel
+  ```
+#### 4.4 Possible problems
+- For windows users, dependency python-levenshtein installation might run into trouble. developers might need to download [.whl](https://www.lfd.uci.edu/~gohlke/pythonlibs/#python-levenshtein) file and install it manually (reference to [link](https://stackoverflow.com/questions/37676623/cant-install-levenshtein-distance-package-on-windows-python-3-5/46414982))
 
 ### 5. Code repos setup
 

diff --git a/src/aaz_dev/docs/Docs/images/add_resource.png b/src/aaz_dev/docs/Docs/images/add_resource.png
diff --git a/src/aaz_dev/docs/Docs/images/argument_edit.png b/src/aaz_dev/docs/Docs/images/argument_edit.png
diff --git a/src/aaz_dev/docs/Docs/images/code_gen.png b/src/aaz_dev/docs/Docs/images/code_gen.png
diff --git a/src/aaz_dev/docs/Docs/images/command_edit.png b/src/aaz_dev/docs/Docs/images/command_edit.png
diff --git a/src/aaz_dev/docs/Docs/images/export.png b/src/aaz_dev/docs/Docs/images/export.png
diff --git a/src/aaz_dev/docs/Docs/images/group_edit.png b/src/aaz_dev/docs/Docs/images/group_edit.png
diff --git a/src/aaz_dev/docs/Docs/images/group_edit1.png b/src/aaz_dev/docs/Docs/images/group_edit1.png
diff --git a/src/aaz_dev/docs/Docs/images/module_select.png b/src/aaz_dev/docs/Docs/images/module_select.png
diff --git a/src/aaz_dev/docs/Docs/images/workspace.png b/src/aaz_dev/docs/Docs/images/workspace.png
diff --git a/src/aaz_dev/docs/Docs/usage/cli_generator_usage.md b/src/aaz_dev/docs/Docs/usage/cli_generator_usage.md
@@ -1,11 +1,47 @@
 # CLI Generator Usage
 ---
-
-## Profile and Command
+## Command Generation
 ---
+### 1. Choose Command Model
+CLI commands are separated into different command models in Azure CLI repo or Azure CLI extension repo. Before generate CLI command, select the target command module.
+![model_select](/Docs/images/module_select.png)
+### 2. Generate Commands
+In the commands display page, check the commands exported from [model editor](#/Workspace), and select the target api version, then click the top-right `Generate` buttton. CLI command code generated from AAZ Development Tool has been added into your cloned local azure-cli directory for further debugging and testing. 
+![code_gen](/Docs/images/code_gen.png)
 
-## Argument
+## About
 ---
+### Azure CLI vs Azure CLI Extension
+
+#### CLI Modules
+
+|                                   PROS                                  |                                                                             CONS                                                                             |
+|:-----------------------------------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------:|
+| Comes automatically with the CLI. No dedicated installation required.   | Strictly tied to CLI release schedule                                                                                                                        |
+| Unlikely to be broken by changes to azure-cli-core (with test coverage) | STRICTLY tied to CLI authoring guidelines. Experimental patterns that may be allowed in extensions could be rejected entirely for inclusion as a CLI module. |
+
+#### Extensions
+
+|                      PROS                      |                         CONS                         |
+|:----------------------------------------------:|:----------------------------------------------------:|
+| Release separate from the CLI release schedule | Requires dedicated installation (az extension add …) |
+| Higher velocity fixes possible                 | Can be broken by changes to the azure-cli-core       |
+| Experimental UX is permissible                 |                                                      |
+| Leverage CLI code generator to generate code   |                                                      |
+
+
+- Common uses for extensions include experimental commands, commands in private or public preview, or to separate between frequently used and rarely used functionality (where infrequently used commands are acquired via extension).
+- Note that if you are trying to get commands into the CLI out of step with the normal release cycle, extensions are your **only** option.
+- Because non-standard, experimental authoring patterns are permitted for extensions, simply trying to "move an extension into the CLI" is often **not** a trivial process and will necessitate a full review with higher scrutiny from the CLI team. Expect to need to make changes.
+- For more details about CLI vs CLI extension, please check [here](https://github.com/Azure/azure-cli/blob/dev/doc/onboarding_guide.md#extension-vs-module)
+- In this editor, only CLI commands are generated. For advanced CLI extension generation techniques, please check [here](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/authoring.md)
+
+
+### Profile
+The Azure CLI supports multiple profiles. Help can be authored to take advantage of this.  
+Commands available, arguments, descriptions and examples all change dynamically based on the profile in use.
 
-### Shorthand Syntax
+The `az cloud update --profile ...` command allows you to switch profiles.  
+You can see an example of this by switching profiles and running `az storage account create --help`.
 
+For more info, please check [here](https://github.com/Azure/azure-cli/blob/dev/doc/authoring_help.md#profile-specific-help)
diff --git a/src/aaz_dev/docs/Docs/usage/command_usage_testing.md b/src/aaz_dev/docs/Docs/usage/command_usage_testing.md
@@ -0,0 +1 @@
+# Command Usage/Testing
diff --git a/src/aaz_dev/docs/Docs/usage/workspace_editor_usage.md b/src/aaz_dev/docs/Docs/usage/workspace_editor_usage.md
@@ -1,14 +1,38 @@
-# Workspace Editor Usage
+# Introduction to Workspace Editor
 ---
-
-## Command Tree
+![Architecture](/Docs/diagrams/out/archutecture/architecture.svg)
+As shown from the overview diagram above, workspace is used to store and edit various customerized command models. Normally, its path is `/Users/yourname/.aaz/workspaces` where all the historical command models' workspace you created are located.
+## Workspace Editor Usage
 ---
+When a new set of CLI commands needs to be generated using AAZDev Tool, [workspace editor](#/Workspace) page is the starting point. 
+### 1. Set Workspace
+Developers can select an existed workspace from the drop-down menu or create a new workspace by typing in a nonexistent name. 
+![workspace](/Docs/images/workspace.png)
 
-## Help & Command Stage
----
+### 2. Add Resource
+After determing the workspace, target resource can be searched and added by filtering swagger modules and API version. As noted before, a resource cannot be added into the same workspace multiple times in different api versions.
+![add_resource](/Docs/images/add_resource.png)
 
-## Command Argument
----
+### 3. Modify Command Model
+According to previous [intro](#/Documents), swagger translator will generate a set of commands from chosen resource with its group and operation parting naming protocol. In the popped command tree, we can: 
+  a. rename command group
+  By clicking and editing the command group name, developer can adjust the swagger-translated long command name into a less redundant version, like: `az network managmentt security-user-configuration` -> `az network mgmt suc`. Also, in the corresponding editing window, short summary can be added as required.
+  ![group_edit](/Docs/images/group_edit.png)
+  ![group_edit1](/Docs/images/group_edit1.png)
+  b. adjust command
+  Click into a command and developers can use the upper `edit` button to do some modifications and add short help message and use the bottom `add` button to add command examples for usage. 
 
-## Command Example
----
+  `Delete` button can be used if current command is no longer needed and needs to be deleted. Meanwhile the corresponding command group can only be deleted when all the children command are deleted. 
+
+  ![command_edit](/Docs/images/command_edit.png)
+
+  c. adjust argument
+  By clicking into an argument under a command, the popped up window can be used to: a) add optional argument names seperated by space; b) change the argument groups for better argument management and display; c) add short summary as argument help message. d) flatten an argument
+  if this argument has only one prop, a more condense argument can be generated using argument `flatten` and the previous argument `arg1` will be named into `arg1-prop` under a seperate `arg1 Group` argument group.
+  ![argument_edit](/Docs/images/argument_edit.png)
+  d. adjust stages
+  As is known in the popped command and argument windows, there are three stages shown: Stable, Preview and Experimental. Detailed infos and support levels can be found in this [link](https://docs.microsoft.com/en-us/cli/azure/reference-types-and-status#what-is-reference-status) where GA(Generally Available) means Stable in workspace editor. A preview or experimental command/argument can be change into a Stable version or be removed in later release as short-time functional testing while a stable one cannot be chaned into the other status or deletd. 
+
+### 4. Export Command Repos
+After all modificationa for command groups, arguments, developer can export current command workspace into your previously folked and cloned AAZ repo using top-right `Export` button, whose path would be `path/to/your/cloned/aaz`. AAZ repo is to maintain all public Atomic Azure Cli command models.
+![export](/Docs/images/export.png)