format tutorial

algorandfoundation · Oct 18, 2023 · bfa631e · bfa631e
1 parent 5476924
commit bfa631e
Show file tree

Hide file tree

Showing 4 changed files with 137 additions and 355 deletions.
diff --git a/docs/get-details/algokit/index.md b/docs/get-details/algokit/index.md
@@ -7,7 +7,16 @@ The Algorand AlgoKit CLI is the one-stop shop tool for developers building on th
 - Toolchain integrations - for languages you love: TypeScript and Python
 - React component generation - frontend design simplified using components generated for each contract method call
 
-## AlgoKit CLI commands
+## AlgoKit Tutorials
+
+The following tutorials guide you through various scenarios:
+
+- [AlgoKit quick start](./tutorials/intro.md)
+- [Creating AlgoKit templates](./tutorials/algokit-template.md)
+
+<iframe width="100%" style="aspect-ratio:16/9" src="https://www.youtube-nocookie.com/embed/MzBRef_Res8" title="Learn How to Build on Algorand in 10 Minutes" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+
+## AlgoKit Features
 
 For details on how to use individual features see the following
 
@@ -22,26 +31,6 @@ 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.
 
-## 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.
-
-- `-h, --help` The help option can be used on any command to get details on any command, its sub-commands and options.
-- `-v, --verbose` Enables DEBUG logging, useful when troubleshooting or if you want to peek under the covers and learn what AlgoKit CLI is doing.
-- `--color / --no-color` Enables or disables output of console styling, we also support the [NO_COLOR](https://no-color.org) environment variable.
-- `--skip-version-check` Skips updated AlgoKit version checking and prompting for that execution, this can also be disabled [permanently on a given machine](./cli-reference.md#version-prompt) with `algokit config version-prompt disable`.
-
-See also the [AlgoKit CLI Reference](./cli-reference.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)
-- [Creating AlgoKit templates](./tutorials/algokit-template.md)
-
-<iframe width="100%" style="aspect-ratio:16/9" src="https://www.youtube-nocookie.com/embed/MzBRef_Res8" title="Learn How to Build on Algorand in 10 Minutes" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
-
 ## Guiding Principles
 
 Algorand AlgoKit is guided by the following solution principles which flow through to the applications created by developers.
@@ -54,3 +43,14 @@ Algorand AlgoKit is guided by the following solution principles which flow throu
 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.
+
+## 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.
+
+- `-h, --help` The help option can be used on any command to get details on any command, its sub-commands and options.
+- `-v, --verbose` Enables DEBUG logging, useful when troubleshooting or if you want to peek under the covers and learn what AlgoKit CLI is doing.
+- `--color / --no-color` Enables or disables output of console styling, we also support the [NO_COLOR](https://no-color.org) environment variable.
+- `--skip-version-check` Skips updated AlgoKit version checking and prompting for that execution, this can also be disabled [permanently on a given machine](./cli-reference.md#version-prompt) with `algokit config version-prompt disable`.
+
+See also the [AlgoKit CLI Reference](./cli-reference.md), which details every command, sub-command and option.
diff --git a/docs/get-details/algokit/tutorials/intro.md b/docs/get-details/algokit/tutorials/intro.md
@@ -1,6 +1,11 @@
 title: AlgoKit Quick Start Guide
 
-AlgoKit is the primary tool used by the Algorand community to develop smart contracts on the Algorand blockchain. It provides the capabilities to develop, test and deploy Algorand smart contracts within minutes! This guide is intended to help you setup AlgoKit and to start developing your application.
+The Algorand AlgoKit CLI is the one-stop shop tool for developers building on the Algorand network. The goal of AlgoKit is to help developers build and launch secure, automated production-ready applications rapidly. AlgoKit contains these components:
+
+- Smart contract templates - kickstart your dApp by selecting from our template library
+- Web3 infrastructure - all the network, database, wallet, block explorer and APIs running locally
+- Toolchain integrations - for languages you love: TypeScript and Python
+- React component generation - frontend design simplified using components generated for each contract method call
 
 ## 10 minute video walkthrough
 
@@ -17,70 +22,68 @@ AlgoKit is the primary tool used by the Algorand community to develop smart cont
 ## Install AlgoKit
 
 === "Windows"
-   > **Note**
-   > This method will install the most recent python3 version [via winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/). If you already have python 3.10+ installed, you may you may prefer to use `pipx install algokit` as explained within the pipx on any OS section so you can control the python version used.
+    > **Note**
+    > This method will install the most recent python3 version [via winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/). If you already have python 3.10+ installed, you may you may prefer to use `pipx install algokit` as explained within the pipx on any OS section so you can control the python version used.
 
-   1. Ensure prerequisites are installed
-      - [Git](https://github.com/git-guides/install-git#install-git-on-windows) (or `winget install git.git`)
-      - [Docker](https://docs.docker.com/desktop/install/windows-install/) (or `winget install docker.dockerdesktop`)
+    - Ensure prerequisites are installed
+        - [Git](https://github.com/git-guides/install-git#install-git-on-windows) (or `winget install git.git`)
+        - [Docker](https://docs.docker.com/desktop/install/windows-install/) (or `winget install docker.dockerdesktop`)
         > **Note**
         > See [our LocalNet documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/localnet.md#prerequisites) for more tips on installing Docker on Windows
-   2. Install Python3 using WinGet
-      1. Install python: `winget install python.python.3.11`
-      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**.
-      3. Install pipx:
-         ```
-         pip install --user pipx
-         python -m pipx ensurepath
-         ```
-      4. Restart the terminal to ensure pipx is available on the path
-      5. Install AlgoKit via pipx: `pipx install algokit`
-      6. Restart the terminal to ensure AlgoKit is available on the path
-   <iframe width="100%" style="aspect-ratio:16/9" src="https://www.youtube-nocookie.com/embed/22RvINnZsRo" title="Installing AlgoKit on Windows" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
-
+    - Install Python3 using WinGet
+        - Install python: `winget install python.python.3.11`
+        - 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**.
+        - Install pipx:
+            ```
+            pip install --user pipx
+            python -m pipx ensurepath
+            ```
+        - Restart the terminal to ensure pipx is available on the path
+        - Install AlgoKit via pipx: `pipx install algokit`
+        - Restart the terminal to ensure AlgoKit is available on the path
+    
+    <iframe width="100%" style="aspect-ratio:16/9" src="https://www.youtube-nocookie.com/embed/22RvINnZsRo" title="Installing AlgoKit on Windows" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 
 === "macOS"
-   > **Note**
-   > This method will install Python 3.10 as a dependency via Homebrew. If you already have python installed, you may prefer to use `pipx install algokit` as explained within the pipx on any OS section so you can control the python version used.
-   
-   1. Ensure prerequisites are installed
-
-      - [Homebrew](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+
-   2. Install using Homebrew `brew install algorandfoundation/tap/algokit`
-   3. Restart the terminal to ensure AlgoKit is available on the path
-   4. [Verify installation](#verify-installation)
-   <iframe width="100%" style="aspect-ratio:16/9" src="https://www.youtube-nocookie.com/embed/zsurtpCGmgE" title="Installing AlgoKit on macOS" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+    > **Note**
+    > This method will install Python 3.10 as a dependency via Homebrew. If you already have python installed, you may prefer to use `pipx install algokit` as explained within the pipx on any OS section so you can control the python version used.
 
+    - Ensure prerequisites are installed
 
-=== "Linux"
-   1. Ensure prerequisites are installed
-      - [Python 3.10+](https://www.python.org/downloads/)
+        - [Homebrew](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**
-        > There is probably a better way to install Python than to download it directly, e.g. your local Linux package manager
-
-      - [pipx](https://pypa.github.io/pipx/#on-linux-install-via-pip-requires-pip-190-or-later)
-      - [Git](https://github.com/git-guides/install-git#install-git-on-linux)
-      - [Docker](https://docs.docker.com/desktop/install/linux-install/)
-
-   2. Continue with step 2 in the following section to install via `pipx` on any OS 
-=== "pipx on any OS"
-
-   To install AlgoKit, run the following command from a terminal.
+        > Docker requires MacOS 11+
+    - Install using Homebrew `brew install algorandfoundation/tap/algokit`
+    - Restart the terminal to ensure AlgoKit is available on the path
+    - [Verify installation](#verify-installation)
 
-   ```shell
-   pipx install algokit
-   ```
+    <iframe width="100%" style="aspect-ratio:16/9" src="https://www.youtube-nocookie.com/embed/zsurtpCGmgE" title="Installing AlgoKit on macOS" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 
-   After the installation completes, **restart the terminal**.
+=== "Linux"
+    - Ensure prerequisites are installed
+        - [Python 3.10+](https://www.python.org/downloads/)
+            > **Note**
+            > There is probably a better way to install Python than to download it directly, e.g. your local Linux package manager
+        - [pipx](https://pypa.github.io/pipx/#on-linux-install-via-pip-requires-pip-190-or-later)
+        - [Git](https://github.com/git-guides/install-git#install-git-on-linux)
+        - [Docker](https://docs.docker.com/desktop/install/linux-install/)
+    - Continue with step 2 in the following section to install via `pipx` on any OS 
+
+=== "OS agnostic"
+    To install AlgoKit, run the following command from a terminal.
+
+    ```shell
+    pipx install algokit
+    ```
+
+    After the installation completes, **restart the terminal**.
 
 Additional AlgoKit videos are available on the [@AlgoDevs YouTube channel](https://youtube.com/@AlgoDevs).