Handle multiple paragraphs of content

.gitignore

@@ -15,4 +15,7 @@ coverage.html
 coverage.out
 
 # Ignore git repos checkout out by examples
-examples/*/.git
+examples/awesome-aks
+
+# ignore initialization files
+.openai

.vscode/launch.json

@@ -0,0 +1,64 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+
+
+        {
+            "name": "Debug IE",
+            "type": "go",
+            "request": "launch",
+            "mode": "debug",
+            "program": "${workspaceRoot}/cmd/ie/ie.go",
+            "cwd": "${workspaceRoot}",
+
+            // Test scenarios
+            //"args": ["test", "${workspaceRoot}/docs/helloWorldDemo.md"],
+            //"args": ["test", "${workspaceRoot}/docs/prerequisitesAndIncludes.md"],
+            "args": ["test", "${workspaceRoot}/docs/environmentVariables.md"],
+            //"args": ["test", "${workspaceRoot}/docs/prerequisitesAndIncludes.md"],
+            "showLog": true,
+            "console": "integratedTerminal"
+        },
+
+        {
+            "name": "Debug EG Ask command",
+            "type": "go",
+            "request": "launch",
+            "mode": "debug",
+            "program": "${workspaceRoot}/examples/eg/main.go",
+            "cwd": "${workspaceRoot}/examples/eg",
+            "args": ["write", "Add some documents to an Azure OpenAI model using RAG."],
+            "showLog": true,
+            "console": "integratedTerminal",
+            "envFile": "${workspaceRoot}/examples/eg/.openai"
+        },
+
+        {
+            "name": "Debug EG Exec Doc",
+            "type": "go",
+            "request": "launch",
+            "mode": "debug",
+            "program": "${workspaceRoot}/cmd/ie/ie.go",
+            "cwd": "${workspaceRoot}/examples/eg",
+            "args": ["execute", "${workspaceRoot}/examples/eg/README.md"],
+            "showLog": true,
+            "console": "integratedTerminal"
+        },
+
+        {
+            "name": "Debug WIP Document",
+            "type": "go",
+            "request": "launch",
+            "mode": "debug",
+            "program": "${workspaceRoot}/cmd/ie/ie.go",
+            "cwd": "${workspaceRoot}",
+            "args": ["test", "${workspaceRoot}/examples/AZD/aks-store-demo/aks-store-demo.md"],
+            //"args": ["test", "${workspaceRoot}/examples/AKS-Automatic/quick-kubernetes-automatic-deploy.md"],
+            "showLog": true,
+            "console": "integratedTerminal"
+        },
+    ]
+}

Dockerfile

@@ -0,0 +1,36 @@
+FROM golang:1.20-alpine
+
+RUN apk update
+RUN apk add --no-cache --update \
+    bash \
+    cargo \
+    git \
+    gcc \
+    libffi-dev \
+    make \
+    musl-dev \
+    openssl-dev \
+    python3 \
+    py3-pip \
+    python3-dev
+
+WORKDIR /InnovationEngine
+
+# Create a virtual environment and install the experimental Authoring Tools and az cli
+RUN python3 -m venv /InnovationEngine/venv
+RUN /InnovationEngine/venv/bin/pip install openai azure-identity requests pygithub
+RUN /InnovationEngine/venv/bin/pip install azure-cli
+
+ENV VIRTUAL_ENV=/InnovationEngine/venv
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
+
+RUN mkdir -p AuthoringTools
+RUN wget -O AuthoringTools/ada.py https://raw.githubusercontent.com/naman-msft/exec/main/tools/ada.py
+RUN chmod +x AuthoringTools/ada.py
+
+# Install the Innovation Engine
+COPY . .
+RUN make build-ie
+ENV PATH="/InnovationEngine/bin:${PATH}"
+
+CMD ["sh", "-c", "ie execute docs/helloWorldDemo.md"]

Makefile

@@ -82,6 +82,12 @@ test-upstream-scenarios:
 		($(MAKE) test-scenario SCENARIO="$${dir}README.md" SUBCRIPTION="$(SUBSCRIPTION)" WORKING_DIRECTORY="$${dir}" ENVIRONMENT="$(ENVIRONMENT)") || exit $$?; \
 	done
 
+test-docs:
+	@echo "Testing all documents in the docs folder"
+	for file in ./docs/*.md; do \
+		($(MAKE) test-scenario SCENARIO="$${file}") || exit $$?; \
+	done
+
 # ------------------------------- Run targets ----------------------------------
 
 run-ie: build-ie

README.md

@@ -49,10 +49,32 @@ command:
 ```bash
 ./bin/ie execute tutorial.md
 ```
+### Building a Container from Source
+
+```bash
+docker build -t ie .
+```
+
+Once built you can run the container and connect to it. Innovation Engine will automatically run an introductory
+document when you execute this command.
+
+```bash
+docker run -it ie
+```
+
+You can override the start command if you want to take control immediately with:
+
+```bash
+docker run -it ie /bin/sh
+```
 
 ## Testing Innovation Engine
 
-Innovation Engine is self-documenting, that is all our documentation is written to be executable. Since Innovation Engine can test the actual results of an execution against the intended reslts this means our documentation is also part of our test suite. In our `scripts` folder you will find a `test_ie.sh` script. Running this will run through all of our documentation in test mode.
+Innovation Engine is self-documenting, that is all our documentation is written to be executable. Since Innovation Engine can test the results of an execution against the intended results this means our documentation is also part of our test suite. Testing against all our documentation is easy as:
+
+```bash
+make test-docs
+```
 
 If you make any changes to the IE code (see Contributing below) we would encourage you to tun the full test suite before issuing a PR.
 
@@ -172,14 +194,27 @@ jobs:
         python3 main.py test README.md
 ```
 
+# Authoring Documents
+
+Authoring documents for use in Innovation Engine is no different from writing high quality documentation for reading. However, it does force you to follow good practice and therefore can sometimes feel a little too involved. That is  every edge case needs to be accounted for so that automated testing will reliably pass. We are therefore working on tools to help you in the authoring process.
+
+These tools are independent of Innovation Engine, however, if you build a container from source they will be included in that container. To use them you will need an Azure OpenAI key (you can use an OpenAI key if you prefer) - be sure to add them in the command below.
+
+```bash
+docker run -it \
+  -e AZURE_OPENAI_API_KEY=$AZURE_OPENAI_API_KEY \
+  -e AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT \
+  ie /bin/sh -c "python AuthoringTools/ada.py"
+```
+
 ## Contributing
 
 This is an open source project. Don't keep your code improvements,
 features and cool ideas to yourself. Please issue pull requests
 against our [GitHub repo](https://github.com/Azure/innovationengine).
 
 Be sure to use our Git pre-commit script to test your contributions
-before committing, simply run the following command: `python3 main.py test test`
+before committing, simply run the following command: `make test-docs`
 
 This project welcomes contributions and suggestions.  Most
 contributions require you to agree to a Contributor License Agreement

cmd/ie/commands/execute.go

@@ -37,7 +37,7 @@ func init() {
 var executeCommand = &cobra.Command{
 	Use:   "execute [markdown file]",
 	Args:  cobra.MinimumNArgs(1),
-	Short: "Execute the commands for an Azure deployment scenario.",
+	Short: "Execute the commands in an executable document.",
 	Run: func(cmd *cobra.Command, args []string) {
 		markdownFile := args[0]
 		if markdownFile == "" {

docs/Authoring-With-Copilot.md

@@ -0,0 +1,46 @@
+# Confgigure Copilot
+
+* CTRL+SHIFT+P
+* Type 'settings.json`
+* Select `Preferences Open User Settings`
+
+Add the following to the `settings.json` file that opens.
+
+<!-- TODO: Ensure this is updated from current user settings -->
+
+```json
+// A set of instructions that will be added to Copilot requests that generate code.
+// Instructions can come from: 
+// - a file in the workspace: `{ "file": "fileName" }`
+// - text in natural language: `{ "text": "Use underscore for field names." }`
+// 
+// Note: Keep your instructions short and precise. Poor instructions can degrade Copilot's quality and performance.
+"github.copilot.chat.codeGeneration.instructions": [
+    {
+    "text": "When writing mardown files each section should have an introductory paragraph, and optional code block and a summary paragraph."
+    },
+],
+```
+
+# Use Copilot
+
+Using Copilot to author docs is easy in Visual Studio Code.
+
+## Initial Authoring
+
+* Create a new document
+* `CTRL+I`
+* Type "Create an executable document which [Objective]"
+* Copilot will attempt to create the document for your, providing heading titles and intro paragraphs
+* Review the document, if any section is missing or needs adjustment position the cursor at that point, hit `CTRL-I`, give the instruction
+* Work through the document creating the code blocks
+
+## Testing
+
+Once you have the document in good shape and you feel it will work you can test it with Innovation Engine.
+
+* Hit CTRL-SHIFT-` to open a WSL terminal (Innovation Engine does not work in PowerShell)
+* Type `ie test filename.md`
+* The document will be executed in test mode, any failure will be reported in the terminal
+* If you want Copilot assistance with errors, position the cursor in the code block where the error occurred and paste the error message
+* Repeat until no errors occur

docs/Common/environmentVariablesFromPrerequisites.md

@@ -0,0 +1,5 @@
+This is a simple prerequisite document that sets a value on a test variable:
+
+```bash
+export ENV_VAR_TEST="Value set in Environment Variables From Prerequisite."
+```

docs/Common/prerequisiteExample.md

@@ -0,0 +1,18 @@
+# Prerequisite Example
+
+This document is a prerequisite example that is used by the [Prerequisites and Includes](prerequisitesAndIncludes.md) document. These two documents together describe and illustrate the use of Prerequisites in Innovation Engine.
+
+## Environment Variables
+
+Lets set an environment variable. This is a good use of pre-requisites because it allows document authors to use the same environment variables across multiple documents. This reduces the opportunity for errors and reduces the content that each author needs to create. Here we will create an 8 character hash that can be used in subsequent commands to ensure each run can create unique values for IDs.
+
+```bash
+export UNIQUE_HASH=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 8)
+```
+
+Now we will echo this to the console. This will both serve to illustrate that this prerequisite has been executed but also allow the user to review the value.
+
+```bash
+echo "Unique hash: $UNIQUE_HASH"
+```
+

docs/README.md

@@ -37,10 +37,13 @@ As an excercise, if you have checked out the Innovation Engine code you could ed
 
 # Next Steps (TBD)
 
+1. [Modes of operation](modesOfOperation.md)
+2. [Hello World Demo](helloWorldDemo.md)
+
 <!--
 TODO: port relevant content from SimDem to here and update to cover IE
-  1. [Modes of operation](modes/README.md)
-  2. [Hello World Demo](demo/README.md)
+
+  2. 
   3. [Build a Hello World script](tutorial/README.md)
   4. [Write SimDem documents](syntax/README.md)
   5. [Special Commands](special_commands/README.md)

docs/environmentVariables.ini

@@ -0,0 +1,2 @@
+EV_FROM_INI="Value set in the .ini file."
+PATH="This value will be ignored as PATH is already set in the environment."

docs/environmentVariables.md

@@ -0,0 +1,63 @@
+# Environment Variables
+
+Executable Documents should use environment variables extensively and should use the following naming conventions to maximize reuse across documents.
+
+## Prerequisites
+
+Prerequisites can set environment variables. For example, lets set a nil value for a test variable:
+
+```bash
+export ENV_VAR_TEST=
+```
+
+Now, if we run the [Environment Variables From Prerequisite](Common/environmentVariablesFromPrerequisites.md) we should find that the value is no longer nil.
+
+```bash
+echo $ENV_VAR_TEST
+```
+
+<!-- expected_results=1.0 -->
+```text
+Value set in Environment Variables From Prerequisite.
+```
+
+## Naming Conventions
+
+In general each Enviroment Variable declared in a primary Executable Document (not a prerequisite document) should us a consistent prefix. This meakes it possible to print (to the console) all variables used by that document. This can be useful in faciliating further work with the resources created. For example, here are three variables that both use the `EV_` prefix.
+
+```bash
+export EV_VAR_ONE=1
+export EV_VAR_TWO=2
+export EV_VAR_THREE=3
+```
+
+Now we can dump all the values set in this document with the following code:
+
+```bash
+printenv | grep '^EV_'
+```
+
+## Initialization Files
+
+It is possible to pass in values for these variables using a `.ini` file. This should have the same name as the executable doc. For example, this document is called `environmentVariables.md` and has an associates `environmentVariables.ini` file which defines the variable `EV_FROM_INI` variable:
+
+```bash
+export EV_FROM_INI="Value set in the .ini file."
+echo $EV_FROM_INI
+```
+
+<!-- expected_similarity=1.0 -->
+```text
+Value set in the .ini file.
+```
+
+However, if the environment variable is already set in the environment then the `.ini` values will not override that setting. For example, `PATH` is normally set on any machine. The `.ini` file for this contains a definition for `PATH` but it will not be used as `PATH` is already set in the environment. That is, your existing environment settings take precedent over the `.ini` file.
+
+```bash
+echo $PATH
+```
+
+<!-- expected_similarity="^(?!.*will be ignored).*" -->
+```text
+/home/username/.local/bin...
+```