Merge pull request #218 from algorandfoundation/docs-updates

docs: Added the intro tutorial
algorandfoundation · Mar 28, 2023 · 8ef890c · 8ef890c · github-actions · Mar 28, 2023
2 parents 390ac19 + 9803ff7
commit 8ef890c
Show file tree

Hide file tree

Showing 25 changed files with 269 additions and 48 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,6 +4,10 @@
 
 We are using the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) standard for commit messages. This allows us to automatically generate release notes and version numbers. We do this via [Python Semantic Release](https://python-semantic-release.readthedocs.io/en/latest/) and [GitHub actions](.github/workflows/cd.yaml).
 
+## Guiding Principles
+
+AlgoKit development is done within the [AlgoKit Guiding Principles](./docs/algokit.md#guiding-principles).
+
 ## Setup (AlgoKit CLI development)
 
 ### Initial setup
@@ -78,7 +82,7 @@ We are using the [Conventional Commits](https://www.conventionalcommits.org/en/v
 
 Markdown documentation can be found within the docs directory of the repo, there is a mixture of handwritten documentation and autogenerated documentation for the CLI tool itself. To autogenerate the CLI documentation from the click source execute `poe docs`, note: this command won't work on Windows.
 
-The CLI docs are generated using Sphinx, and its configuration can be found in `docs\sphinx`. The generated Markdown output is post processed to add a Table of Contents and top level title and the final Markdown is output to `docs\cli`. The commands to achieve this are defined in pyproject.toml under `[tool.poe.tasks]`
+The CLI docs are generated using Sphinx, and its configuration can be found in `docs\sphinx`. The generated Markdown output is post processed to add a Table of Contents and top level title and the final Markdown is output to `docs\cli`. The commands to achieve this are defined in `pyproject.toml` under `[tool.poe.tasks]`
 
 ### Libraries and Tools
 

diff --git a/README.md b/README.md
@@ -1,12 +1,23 @@
 # AlgoKit CLI
 
-The Algorand AlgoKit CLI is the one-stop shop tool for developers building on the Algorand network.
+The Algorand AlgoKit CLI is the one-stop shop tool for developers building on the [Algorand network](https://www.algorand.com/).
 
 AlgoKit gets developers of all levels up and running with a familiar, fun and productive development environment in minutes. The goal of AlgoKit is to help developers build and launch secure, automated production-ready applications rapidly.
 
-[Install AlgoKit](#install) | [Documentation](./docs/algokit.md)
+[Install AlgoKit](#install) | [Quick Start Tutorial](./docs/tutorials/intro.md) | [Documentation](./docs/algokit.md)
 
-## Capabilities
+## What is AlgoKit?
+
+[model image]
+
+AlgoKit compromises of a number of components that make it the one-stop shop tool for developers building on the [Algorand network](https://www.algorand.com/):
+
+- A commandline Interface (CLI) so you can quickly access AlgoKit capabilities
+- A template library to get you started faster
+- A set of framework libraries so you can build faster
+- A local isolated Algorand network so you can simulate real transactions and workloads
+
+## What can AlgoKit help me do?
 
 The set of capabilities supported by AlgoKit will evolve over time, but currently includes:
 
@@ -20,24 +31,11 @@ Future capabilities are likely to include:
 - Quickly deploy [standardised](https://github.com/algorandfoundation/ARCs/#arcs-algorand-requests-for-comments), audited smart contracts
 - Building and deploying Algorand dApps
 
-## Guiding Principles
-
-Algorand AlgoKit is guided by the following solution principles which flow through to the applications created by developers.
-
-1. **Cohesive developer tool suite**: Using AlgoKit should feel professional and cohesive, like it was designed to work together, for the developer; not against them. Developers are guided towards delivering end-to-end, high quality outcomes on MainNet so they and Algorand are more likely to be successful.
-2. **Seamless onramp**: New developers have a seamless experience to get started and they are guided into a pit of success with best practices, supported by great training collateral; you should be able to go from nothing to debugging code in 5 minutes.
-3. **Leverage existing ecosystem**: AlgoKit functionality gets into the hands of Algorand developers quickly by building on top of the existing ecosystem wherever possible and aligned to these principles.
-4. **Sustainable**: AlgoKit should be built in a flexible fashion with long-term maintenance in mind. Updates to latest patches in dependencies, Algorand protocol development updates, and community contributions and feedback will all feed in to the evolution of the software.
-5. **Secure by default**: Include defaults, patterns and tooling that help developers write secure code and reduce the likelihood of security incidents in the Algorand ecosystem. This solution should help Algorand be the most secure Blockchain ecosystem.
-6. **Extensible**: Be extensible for community contribution rather than stifling innovation, bottle-necking all changes through the Algorand Foundation and preventing the opportunity for other ecosystems being represented (e.g. Go, Rust, etc.). This helps make developers feel welcome and is part of the developer experience, plus it makes it easier to add features sustainably.
-7. **Meet developers where they are**: Make Blockchain development mainstream by giving all developers an idiomatic development experience in the operating system, IDE and language they are comfortable with so they can dive in quickly and have less they need to learn before being productive.
-8. **Modular components**: Solution components should be modular and loosely coupled to facilitate efficient parallel development by small, effective teams, reduced architectural complexity and allowing developers to pick and choose the specific tools and capabilities they want to use based on their needs and what they are comfortable with.
-
 ## Is this for me?
 
 The target audience for this tool is software developers building applications on the Algorand network. A working knowledge of using a command line interfaces and experience using the supported programming languages is assumed.
 
-## Contributing
+## How can I contribute?
 
 This is an open source project managed by the Algorand Foundation. See the [contributing page](CONTRIBUTING.md) to learn about making improvements to the CLI tool itself, including developer setup instructions.
 
@@ -86,26 +84,27 @@ AlgoKit can be installed using OS specific package managers, or using the python
    2. Restart the terminal to ensure Python and pip are available on the path
 
       > **Note**
-      > Windows has a feature called **App Execution Aliases** that provides redirects for the Python command that guide users to the 
-        Windows Store. Unfortunately these aliases can prevent normal execution of Python if Python is installed via other means, to disable them
-        search for **Manage app execution aliases** from the start menu, and then turn off entries listed as 
-        **App Installer python.exe** or **App Installer python3.exe**. 
+      > Windows has a feature called **App Execution Aliases** that provides redirects for the Python command that guide users to the
+      > Windows Store. Unfortunately these aliases can prevent normal execution of Python if Python is installed via other means, to disable them
+      > search for **Manage app execution aliases** from the start menu, and then turn off entries listed as
+      > **App Installer python.exe** or **App Installer python3.exe**.
 
-   3. Install pipx: 
+   3. Install pipx:
       ```
       pip install --user pipx
       python -m pipx ensurepath
       ```
-   4. Install AlgoKit via pipx: `python -m pipx install algokit` 
+   4. Install AlgoKit via pipx: `python -m pipx install algokit`
    5. Restart the terminal to ensure AlgoKit is available on the path
- 
+
 3. [Verify installation](#verify-installation)
 
-### Maintenance 
-  Some useful commands for updating or removing AlgoKit in the future.
-  - To update AlgoKit: `pipx upgrade algokit`
-  - To remove AlgoKit: `pipx uninstall algokit`
+### Maintenance
+
+Some useful commands for updating or removing AlgoKit in the future.
 
+- To update AlgoKit: `pipx upgrade algokit`
+- To remove AlgoKit: `pipx uninstall algokit`
 
 ## Install AlgoKit on Mac
 
@@ -117,17 +116,19 @@ AlgoKit can be installed using OS specific package managers, or using the python
    - [Brew](https://docs.brew.sh/Installation)
    - [Git](https://github.com/git-guides/install-git#install-git-on-mac) should already be available if brew is installed
    - [Docker](https://docs.docker.com/desktop/install/mac-install/), (or `brew install --cask docker`)
-      > **Note**
-      > Docker requires MacOS 11+
+     > **Note**
+     > Docker requires MacOS 11+
 
-2. Install using Brew  `brew install algorandfoundation/tap/algokit`
+2. Install using Brew `brew install algorandfoundation/tap/algokit`
 3. Restart the terminal to ensure AlgoKit is available on the path
 4. [Verify installation](#verify-installation)
 
-### Maintenance 
-  Some useful commands for updating or removing AlgoKit in the future.
-  - To update AlgoKit: `brew upgrade algokit`
-  - To remove AlgoKit: `brew uninstall algokit`
+### Maintenance
+
+Some useful commands for updating or removing AlgoKit in the future.
+
+- To update AlgoKit: `brew upgrade algokit`
+- To remove AlgoKit: `brew uninstall algokit`
 
 ## Install AlgoKit on Linux
 
@@ -157,11 +158,12 @@ AlgoKit can be installed using OS specific package managers, or using the python
 3. Restart the terminal to ensure AlgoKit is available on the path
 4. [Verify installation](#verify-installation)
 
-### Maintenance 
-  Some useful commands for updating or removing AlgoKit in the future.
-  - To update AlgoKit: `pipx upgrade algokit`
-  - To remove AlgoKit: `pipx uninstall algokit`
+### Maintenance
+
+Some useful commands for updating or removing AlgoKit in the future.
 
+- To update AlgoKit: `pipx upgrade algokit`
+- To remove AlgoKit: `pipx uninstall algokit`
 
 ## Verify installation
 

diff --git a/docs/algokit.md b/docs/algokit.md
@@ -14,7 +14,7 @@ For details on how to use individual features see the following
 - [Init](./features/init.md) - Quickly initialize new projects using official Algorand Templates or community provided templates.
 - [LocalNet](./features/localnet.md) - Manage a locally sandboxed private Algorand network.
 
-## AlgoKit CLI options
+## Common AlgoKit CLI options
 
 AlgoKit has a number of global options that can impact all commands. Note: these global options must be appended to `algokit` and appear before a command, e.g. `algokit -v localnet start`, but not `algokit localnet start -v`. The exception to this is `-h`, which can be appended to any command or sub-command to see contextual help information.
 
@@ -24,3 +24,23 @@ AlgoKit has a number of global options that can impact all commands. Note: these
 - `--skip-version-check` Skips updated AlgoKit version checking and prompting for that execution, this can also be disabled [permanently on a given machine](./cli/index.md#version-prompt) with `algokit config version-prompt disable`.
 
 See also the [AlgoKit CLI Reference](./cli/index.md), which details every command, sub-command and option.
+
+## AlgoKit Tutorials
+
+The following tutorials guide you through various scenarios:
+
+- [AlgoKit quick start](./tutorials/intro.md)
+- [Production-ready smart contracts](./tutorials/smart-contracts.md)
+
+## Guiding Principles
+
+Algorand AlgoKit is guided by the following solution principles which flow through to the applications created by developers.
+
+1. **Cohesive developer tool suite**: Using AlgoKit should feel professional and cohesive, like it was designed to work together, for the developer; not against them. Developers are guided towards delivering end-to-end, high quality outcomes on MainNet so they and Algorand are more likely to be successful.
+2. **Seamless onramp**: New developers have a seamless experience to get started and they are guided into a pit of success with best practices, supported by great training collateral; you should be able to go from nothing to debugging code in 5 minutes.
+3. **Leverage existing ecosystem**: AlgoKit functionality gets into the hands of Algorand developers quickly by building on top of the existing ecosystem wherever possible and aligned to these principles.
+4. **Sustainable**: AlgoKit should be built in a flexible fashion with long-term maintenance in mind. Updates to latest patches in dependencies, Algorand protocol development updates, and community contributions and feedback will all feed in to the evolution of the software.
+5. **Secure by default**: Include defaults, patterns and tooling that help developers write secure code and reduce the likelihood of security incidents in the Algorand ecosystem. This solution should help Algorand be the most secure Blockchain ecosystem.
+6. **Extensible**: Be extensible for community contribution rather than stifling innovation, bottle-necking all changes through the Algorand Foundation and preventing the opportunity for other ecosystems being represented (e.g. Go, Rust, etc.). This helps make developers feel welcome and is part of the developer experience, plus it makes it easier to add features sustainably.
+7. **Meet developers where they are**: Make Blockchain development mainstream by giving all developers an idiomatic development experience in the operating system, IDE and language they are comfortable with so they can dive in quickly and have less they need to learn before being productive.
+8. **Modular components**: Solution components should be modular and loosely coupled to facilitate efficient parallel development by small, effective teams, reduced architectural complexity and allowing developers to pick and choose the specific tools and capabilities they want to use based on their needs and what they are comfortable with.
diff --git a/docs/architecture-decisions/2022-11-14_sandbox-approach.md b/docs/architecture-decisions/2022-11-14_sandbox-approach.md
@@ -23,7 +23,7 @@ In order for AlgoKit to facilitate a productive development experience it needs
 
 ## Principles
 
-- **[AlgoKit Guiding Principles](../../README.md#Guiding-Principles)** - specifically Seamless onramp, Leverage existing ecosystem, Meet devs where they are
+- **[AlgoKit Guiding Principles](../../docs/algokit.md#Guiding-Principles)** - specifically Seamless onramp, Leverage existing ecosystem, Meet devs where they are
 - **Lightweight** - the solution should have as low an impact as possible on resources on the developers machine
 - **Fast** - the solution should start quickly, which makes for a nicer experience locally and also allows it to be used for continuous integration automation testing
 

diff --git a/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md b/docs/architecture-decisions/2023-01-12_smart-contract-deployment.md
@@ -41,7 +41,7 @@ This decision record covers the different options and high level design for how
 
 ## Principles
 
-- [AlgoKit Guiding Principles](../../README.md#Guiding-Principles) - specifically:
+- [AlgoKit Guiding Principles](../../docs/algokit.md#Guiding-Principles) - specifically:
   - **Cohesive developer tool suite**
   - **Seamless onramp**
   - **Secure by default**

diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -64,6 +64,8 @@
 
 AlgoKit is your one-stop shop to develop applications on the Algorand blockchain.
 
+If you are getting started, please see the quick start tutorial: [https://bit.ly/algokit-intro-tutorial](https://bit.ly/algokit-intro-tutorial).
+
 ```shell
 algokit [OPTIONS] COMMAND [ARGS]...
 ```
@@ -88,7 +90,8 @@ Skip version checking and prompting.
 
 ## bootstrap
 
-Bootstrap AlgoKit project dependencies.
+Expedited initial setup for any developer by bootstrapping dependencies and other
+key development environment setup activities.
 
 ```shell
 algokit bootstrap [OPTIONS] COMMAND [ARGS]...

diff --git a/docs/imgs/algokit-intro-video-thumbnail.jpg b/docs/imgs/algokit-intro-video-thumbnail.jpg
diff --git a/docs/imgs/algokitartifacts.png b/docs/imgs/algokitartifacts.png
diff --git a/docs/imgs/algokitdemo.png b/docs/imgs/algokitdemo.png
diff --git a/docs/imgs/algokitplayground.png b/docs/imgs/algokitplayground.png
diff --git a/docs/imgs/dappflow.png b/docs/imgs/dappflow.png
diff --git a/docs/imgs/dappflow1.png b/docs/imgs/dappflow1.png
diff --git a/docs/imgs/dappflow2.png b/docs/imgs/dappflow2.png
diff --git a/docs/imgs/dappflow3.png b/docs/imgs/dappflow3.png
diff --git a/docs/imgs/dappflow4.png b/docs/imgs/dappflow4.png
diff --git a/docs/imgs/dappflow5.png b/docs/imgs/dappflow5.png
diff --git a/docs/imgs/dappflow6.png b/docs/imgs/dappflow6.png
diff --git a/docs/imgs/dappflow_transaction.png b/docs/imgs/dappflow_transaction.png
diff --git a/docs/imgs/localnet.png b/docs/imgs/localnet.png
File	Stmts	Miss	Cover	Missing
src/algokit
__init__.py	15	7	53%	6–13, 17–24, 32–34
__main__.py	2	2	0%	1–3
src/algokit/cli
completions.py	105	2	98%	78, 93
doctor.py	48	3	94%	138–140
goal.py	30	1	97%	37
init.py	180	16	91%	261–262, 284, 287–289, 300, 344, 370, 410, 419–421, 424–429, 442
localnet.py	91	3	97%	157, 178–179
src/algokit/core
bootstrap.py	133	16	88%	109, 132, 197, 200, 206–220
conf.py	30	4	87%	13, 17, 25, 27
doctor.py	65	7	89%	67–69, 92–94, 134
log_handlers.py	68	7	90%	50–51, 63, 112–116, 125
proc.py	45	1	98%	98
sandbox.py	117	15	87%	84–91, 102, 167, 183, 198–200, 216
version_prompt.py	73	8	89%	27–28, 40, 59–62, 80, 109
TOTAL	1140	92	92%