You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Contact Information for Exec Docs](#contact-information-for-exec-docs)
20
21
22
+
I'll update the highlighted section with the clarified information about command execution limitations:
23
+
24
+
## Selecting Documentation for Exec Docs
25
+
26
+
Not all documentation is suitable for conversion to Exec Docs. Use these filters to determine if a document can be effectively converted:
27
+
28
+
1.**Supported Code Block Types**
29
+
- The document must contain code blocks using at least one of these types:
30
+
-`bash`
31
+
-`azurecli`
32
+
-`azure-cli-interactive`
33
+
-`azurecli-interactive`
34
+
-`terraform`
35
+
36
+
**Example:**
37
+
```markdown
38
+
```bash
39
+
az group create --name myResourceGroup --location eastus
40
+
```
41
+
```
42
+
43
+
>**Note:** This rule does not apply to output code blocks, which are used to display the results of commands, scripts, or other operations. These blocks help in illustrating what the expected output should look like. They include, but are not limited to, the following types: _output, json, yaml, console, text, and log._
44
+
45
+
>**Note:** While Innovation Engine can _parse_ a code block of any type, given its current features, it can only _execute_ code blocks of the types above. So, it is important to ensure that the code blocks in your Exec Doc are of the types above.
46
+
47
+
2.**Command Execution Limitations**
48
+
-**Not supported for direct execution:**
49
+
- PowerShell scripts
50
+
- GUI-based instructions
51
+
- Direct code blocks containing Python, SQL, or other languages (these should be executed via BASH commands)
52
+
53
+
-**Supported execution context:**
54
+
- Commands that run in a Linux/bash environment
55
+
- Azure CLI commands
56
+
- Terraform commands (works without any special setup)
57
+
- Python scripts executed via BASH (e.g., `python myApp.py`)
58
+
- SQL queries executed via database CLI tools
59
+
60
+
**Example of supported command:**
61
+
```markdown
62
+
```bash
63
+
export VM_NAME="myVM"
64
+
az vm create --name $VM_NAME --resource-group myResourceGroup --image UbuntuLTS
65
+
```
66
+
```
67
+
68
+
**Example of unsupported command:**
69
+
```markdown
70
+
```sql
71
+
SELECT * FROM myTable WHERE id = 1;
72
+
```
73
+
```
74
+
75
+
>**Note:** The key principle is that if a code block can be executed in a BASH terminal as written (the way a human would execute it), then it will work with Exec Docs.
- Standard Azure resource operations (create, read, update, delete)
80
+
- Commands running within the user's subscription scope
81
+
- Standard service deployments (VMs, storage, networking)
82
+
83
+
- **Not supported currrently:**
84
+
- Commands requiring elevated Microsoft Graph API permissions
85
+
- Operations needing KeyVault special access
86
+
- Cross-subscription or tenant-level operations
87
+
- Commands requiring admin consent
88
+
89
+
**Example of supported command:**
90
+
```markdown
91
+
```bash
92
+
az group create --name myResourceGroup --location eastus
93
+
```
94
+
```
95
+
96
+
**Example of unsupported command:**
97
+
```markdown
98
+
```bash
99
+
# This requires elevated Graph API permissions and would fail
100
+
az ad app create --display-name myApp --native-app
101
+
```
102
+
```
103
+
104
+
This filter system ensures that you select documentation that can be effectively transformed into executable docs that provide value through automated deployment capabilities. Please reach out to the [Exec Docs Team](#contact-information-for-exec-docs) if you have any questions about the suitability of a document for conversion to an Exec Doc.
105
+
21
106
## How to Write an Exec Doc
22
107
23
108
Follow these steps in sequence to write an Exec Doc either by converting an existing Azure Doc i.e. building on top of the author's work or from scratch i.e. you are the author _(read the Notes in any step for more information)_:
@@ -81,33 +166,14 @@ Check if all prerequisites below are met before writing the Exec Doc. ***If any
81
166
│ └── my-script.yaml
82
167
```
83
168
84
-
6. Code blocks are used to provide examples, commands, or other code snippets in Exec Docs. They are distinguished by a triple backtick (```) at the start and end of the block.
85
-
86
-
Ensure that the Exec Doc contains at least 1 code block and every input code block's type in the Exec Doc is taken from this list:
87
-
88
-
- bash
89
-
- azurecli
90
-
- azure-cli-interactive
91
-
- azurecli-interactive
92
-
93
-
**Example:**
94
-
95
-
```bash
96
-
az group create --name $MY_RESOURCE_GROUP_NAME --location $REGION
97
-
```
98
-
99
-
>**Note:** This rule does not apply to output code blocks, which are used to display the results of commands, scripts, or other operations. These blocks help in illustrating what the expected output should look like. They include, but are not limited to, the following types: _output, json, yaml, console, text, and log._
100
-
101
-
>**Note:** While Innovation Engine can _parse_ a code block of any type, given its current features, it can only _execute_ code blocks of the types above. So, it is important to ensure that the code blocks in your Exec Doc are of the types above.
102
-
103
-
7. Headings are used to organize content in a document. The number of hashes indicates the level of the heading. For example, a single hash (#) denotes an h1 heading, two hashes (##) denote an h2 heading, and so on. Innovation Engine uses headings to structure the content of an Exec Doc and to provide a clear outline of the document's contents.
169
+
6. Headings are used to organize content in a document. The number of hashes indicates the level of the heading. For example, a single hash (#) denotes an h1 heading, two hashes (##) denote an h2 heading, and so on. Innovation Engine uses headings to structure the content of an Exec Doc and to provide a clear outline of the document's contents.
104
170
105
171
Ensure there is at least one h1 heading in the Exec Doc, denoted by a single hash (#) at the start of the line.
106
172
107
173
**Example:**
108
174
109
175
```markdown
110
-
# Quickstart: Deploy an Azure Kubernetes Service (AKS) cluster using Azure CLI
176
+
# Quickstart: Deploy an Azure Kubernetes Service (AKS) cluster using Azure CLI
111
177
```
112
178
113
179
### Writing Requirements
@@ -349,12 +415,12 @@ Check if all prerequisites below are met before writing the Exec Doc. ***If any
349
415
350
416
**Deeplink Template:**
351
417
```markdown
352
-
[](https://ms.portal.azure.com/#view/Microsoft_Azure_CloudNative/SubscriptionSelectionPage.ReactView/isLearnMode~/true/referer/docs/tutorialKey/<add_file_path_of_Exec_Doc>)
418
+
[](https://ms.portal.azure.com/#view/Microsoft_Azure_CloudNative/SubscriptionSelectionPage.ReactView/isLearnMode~/true/referer/docs/tutorialKey/<add_file_path_of_Exec_Doc>)
353
419
```
354
420
355
421
**Deeplink for Example Exec Doc:**
356
422
```markdown
357
-
[](https://ms.portal.azure.com/#view/Microsoft_Azure_CloudNative/SubscriptionSelectionPage.ReactView/isLearnMode~/true/referer/docs/tutorialKey/azure-docs%2farticles%2faks%2fquick-kubernetes-deploy-cli.md)
423
+
[](https://ms.portal.azure.com/#view/Microsoft_Azure_CloudNative/SubscriptionSelectionPage.ReactView/isLearnMode~/true/referer/docs/tutorialKey/azure-docs%2farticles%2faks%2fquick-kubernetes-deploy-cli.md)
0 commit comments