{"id":13794571,"url":"https://github.com/Azure/InnovationEngine","last_synced_at":"2025-05-12T21:31:42.644Z","repository":{"id":65803524,"uuid":"493838614","full_name":"Azure/InnovationEngine","owner":"Azure","description":"An experiment in simplicity for complex environments","archived":false,"fork":false,"pushed_at":"2024-11-14T04:44:51.000Z","size":692,"stargazers_count":35,"open_issues_count":54,"forks_count":18,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-14T05:03:18.736Z","etag":null,"topics":["azure-cli","bash","markdown-parser"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Azure.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-18T22:04:17.000Z","updated_at":"2024-11-09T01:32:23.000Z","dependencies_parsed_at":"2024-01-14T00:53:43.380Z","dependency_job_id":"d3496c47-ba6d-4083-89c2-f978467c1434","html_url":"https://github.com/Azure/InnovationEngine","commit_stats":{"total_commits":284,"total_committers":22,"mean_commits":"12.909090909090908","dds":0.426056338028169,"last_synced_commit":"5f17eda1f60832a6cb1c8c0aadece07a21e4ea1b"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2FInnovationEngine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2FInnovationEngine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2FInnovationEngine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure%2FInnovationEngine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Azure","download_url":"https://codeload.github.com/Azure/InnovationEngine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225157000,"owners_count":17429698,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["azure-cli","bash","markdown-parser"],"created_at":"2024-08-03T23:00:43.688Z","updated_at":"2025-05-12T21:31:42.620Z","avatar_url":"https://github.com/Azure.png","language":"Go","funding_links":[],"categories":["Quality Assurance"],"sub_categories":[],"readme":"# Overview\n\nInnovation Engine is a tool for rapid innovation and simplification. Innovation Engine is \na CLI tool known as ie that enables execution and testing of Executable Documentation.\n\nExecutable Documentation is a shell script, leveraging any tools available in the shell and embedding it within documentation. That is, it takes standard markdown language and amplifies it by allowing the code commands within the document to be executed interacted with an executed.\nThis means that for the first time documentation is also code. \n\nUsing Innovation Engine you can:\n\n  * Describe the intent and expected behaviour of your shell scripts in markdown rather than comments. This means you documentation can contain hyperlinks, images, formatting etc. It can be rendered as standard markdown, e.g. as a `README.md` or a wiki page in GitHub, or as a web page. It also means that there is no need to keep two separate documents in sync. Editing code and documentation is now done in a single file.\n  * Execute the code within your documentation just like any other shell script. The Innovation Engine CLI tool will parse out your script and execute it for you, as if it were a standard shell script.\n  * Execute in \"learn mode\" onboarding new team members can be hard. Telling them to learn from a script is often going too deep too quickly, while starting from documentation presents the challenge of finding the right starting point for all skill levels. Innovation Engine allows individuals to work through the documented script at their own pace. Telling the engine to execute up to the point that they can follow and then working through step by step guided by the documentation.\n  * Test the intended results of a script through the inclusion of self-documenting results blocks. This allows you to test your documentation/scripts in the CLI before merging, or in your CI/CD environment using, for example, GitHub Actions.\n  * Extract the executable script from the documentation for use without Innovation Engine in the workflow.\n\nInnovation Engine is designed to be reused in custom user experiences. For example, Microsoft Azure uses Innovation Engine to provide documentation on their Learn site, which can also be executed in the Azure Portal. This allows users to explore \"good practice\" documentation at the pace they prefer. They can simply read the documentation, they can interactively work through it in a customer Portal interface or they can simply go ahead and run it in order to deploy the architecture described within the document.\n\n## Install Innovation Engine CLI\n\nTo install the Innovation Engine CLI, run the following commands. To install a specific version, set VERSION to the desired release number, such as \"v0.1.3\".\nYou can find all releases [here](https://github.com/Azure/InnovationEngine/releases).\n\n```bash\nVERSION=\"latest\"\nwget -q -O ie https://github.com/Azure/InnovationEngine/releases/download/$VERSION/ie\n\n# Setup permissions \u0026 move to the local bin\nchmod +x ie\nmkdir -p ~/.local/bin\nmv ie ~/.local/bin\n```\n\n## Build Innovation Engine from Source\n\nPaste the following commands into the shell. This will \nclone the Innovation Engine repo, install the requirements, and build out the \nInnovation Engine executable.\n\n```bash\ngit clone https://github.com/Azure/InnovationEngine;\ncd InnovationEngine;\nmake build-ie;\n```\n\nNow you can run the Innovation Engine tutorial with the following \ncommand:\n\n```bash\n./bin/ie execute tutorial.md\n```\n\n## Testing Innovation Engine\n\nInnovation 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.\n\nIf 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.\n\nTo manual test a document it is best to run in `interactive` mode (see below). This mode provides an interactive console for reading and executing the content of Executable Documentation.\n\n# How to Use Innovation Engine\nThe general format to run an executable document is: \n`ie \u003cMODE_OF_OPERATION\u003e \u003cMARKDOWN_FILE\u003e`\n\n## Modes of Operation\nToday, executable documentation can be run in 3 modes of operation:\n\nInteractive: Displays the descriptive text of the tutorial and pauses at code \nblocks and headings to allow user interaction \n`ie interactive tutorial.md`\n\nTest: Runs the commands and then verifies that the output is sufficiently \nsimilar to the expected results (recorded in the markdown file) to be \nconsidered correct. `ie test tutorial.md`\n\nExecute: Reads the document and executes all of the code blocks not pausing for \ninput or testing output. Essentially executes a markdown file as a script. \n`ie execute tutorial.md`\n\n## Use Innovation Engine with any URL\n\nDocumentation does not need to be stored locally in order to run IE with it. With v0.1.3 and greater, you can run `ie execute`, `ie interactive`, and `ie test` with any URL that points to a public markdown file, including raw GitHub URLs. See the below demo:\n\nhttps://github.com/Azure/InnovationEngine/assets/55719566/ce37f53c-9876-42b9-a033-1e4acaeb9d50\n\n## Use Executable documentation for Automated Testing\nOne of the core benefits of executable documentation is the ability to run \nautomated testing on markdown file. This can be used to ensure freshness of \ncontent.\n\nIn order to do this one will need to combine innovation engine executable \ndocumentation syntax with GitHub actions. \n\nIn order to test if a command or action ran correctly executable documentation \nneeds something to compare the results against. This requirement is met with \nresult blocks.\n\n### Result Blocks\nResult blocks are distinguished in Executable documentation by a custom \nexpected_similarity comment tag followed by a code block. For example\n\n\\\u003c!--expected_similarity=0.8--\u003e\n\u003c!--expected_similarity=0.8--\u003e\n```text\nHello world\n```\nIn the above example we have escaped the comment syntax so that it shows up in \nmarkdown. Otherwise, the tag of expected_similarity is completely invisible.\n\nThe expected similarity value is a floating point number between 0 and 1 which \nspecifies how closely the output needs to match the results block. 0 being no \nsimilarity, 1 being an exact match.\n\n\u003e**Note** It may take a little bit of trial and error to find the exact value for expected_similarity.\n\n### Environment Variables\n\nYou can pass in variable declarations as an argument to the ie CLI command using the 'var' parameter. For example:\n```bash\nie execute tutorial.md --var REGION=eastus\n```\n\nCLI argument variables override environment variables declared within the markdown document,\nwhich override preexisting environment variables.\n\nLocal variables declared within the markdown document will override CLI argument variables.\n\nLocal variables (ex: `REGION=eastus`) will not persist across code blocks. It is recommended\nto instead use environment variables (ex: `export REGION=eastus`).\n\n### Setting Up GitHub Actions to use Innovation Engine\n\nAfter documentation is set up to take advantage of automated testing a github \naction will need to be created to run testing on a recurring basis. The action \nwill simply create a basic Linux container, install Innovation Engine \nExecutable Documentation and run Executable documentation in the Test mode on \nwhatever markdown files are specified.\n\nIt is important to note that if you require any specific access or cli tools \nnot included in standard bash that will need to be installed in the container. \nThe following example is how this may be done for a document which runs Azure \ncommands.\n\n```yml\nname: 00-testing\n\non:\n  push:\n    branches:\n    - main\n\n  workflow_dispatch:\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v2\n    - uses: azure/login@v1\n      with:\n        creds: ${{ secrets.AZURE_CREDENTIALS }}\n    - name: Deploy\n      env:\n        AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS }}\n        GITHUB_SHA: ${{ github.sha }}\n      run: |\n        cd $GITHUB_WORKSPACE/\n        git clone https://github.com/Azure/InnovationEngine/tree/ParserAndExecutor\n        cd innovationEngine\n        pip3 install -r requirements.txt\n        cp ../../articles/quick-create-cli.md README.md\n        python3 main.py test README.md\n```\n\n## Contributing\n\nThis is an open source project. Don't keep your code improvements,\nfeatures and cool ideas to yourself. Please issue pull requests\nagainst our [GitHub repo](https://github.com/Azure/innovationengine).\n\nBe sure to use our Git pre-commit script to test your contributions\nbefore committing, simply run the following command: `python3 main.py test test`\n\nThis project welcomes contributions and suggestions.  Most\ncontributions require you to agree to a Contributor License Agreement\n(CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit\nhttps://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine\nwhether you need to provide a CLA and decorate the PR appropriately\n(e.g., label, comment). Simply follow the instructions provided by the\nbot. You will only need to do this once across all repos using our\nCLA.\n\nThis project has adopted\nthe\n[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see\nthe\n[Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with\nany additional questions or comments.\n\n\n## Trademarks\n\nThis project may contain trademarks or logos for projects, products, or \nservices. Authorized use of Microsoft trademarks or logos is subject to and \nmust follow [Microsoft's Trademark \u0026 Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).\nUse of Microsoft trademarks or logos in modified versions of this project must \nnot cause confusion or imply Microsoft sponsorship. Any use of third-party \ntrademarks or logos are subject to those third-party's policies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAzure%2FInnovationEngine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAzure%2FInnovationEngine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAzure%2FInnovationEngine/lists"}