docs: minor rewrite in quick start guide (#64)

* docs: minor rewrite in quick start guide * chore: addressing pr comments
algorandfoundation · Apr 3, 2024 · b067148 · b067148
1 parent 5c68a4f
commit b067148
Show file tree

Hide file tree

Showing 15 changed files with 330 additions and 246 deletions.
diff --git a/...r_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-cd.yaml b/...r_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-cd.yaml
@@ -31,7 +31,7 @@ jobs:
         run: pipx install algokit
 
       - name: Bootstrap dependencies
-        run: algokit bootstrap all --project-name 'production_beaker_smart_contract_python'
+        run: algokit project bootstrap all --project-name 'production_beaker_smart_contract_python'
 
       - name: Configure git
         shell: bash

diff --git a/...r_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-ci.yaml b/...r_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-ci.yaml
@@ -27,7 +27,7 @@ jobs:
         run: algokit localnet start
 
       - name: Bootstrap dependencies
-        run: algokit bootstrap all --project-name 'production_beaker_smart_contract_python'
+        run: algokit project bootstrap all --project-name 'production_beaker_smart_contract_python'
 
       - name: Configure git
         shell: bash

diff --git a/examples/generators/production_beaker_smart_contract_python/README.md b/examples/generators/production_beaker_smart_contract_python/README.md
@@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta
 
 > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension.
 
-### Initial setup
-
-1. Clone this repository locally
-2. Install pre-requisites:
-   - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine.
-   - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later.
-   - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will:
-     - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+
-     - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies
-     - Copy `.env.template` to `.env`
-   - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you.
-   - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`).
-3. Open the project and start debugging / developing via:
-   - Terminal
-     1. Run `algokit project run build` to build all contracts in the project
-     2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network.
-   - VS Code (Launch Configurations)
-     1. Open the repository root in VS Code
-     2. Install recommended extensions
-     3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging.
-        > **Note**
-        > If using Windows: Before running for the first time you will need to select the Python Interpreter.
-        1. Open the command palette (Ctrl/Cmd + Shift + P)
-        2. Search for `Python: Select Interpreter`
-        3. Select `./.venv/Scripts/python.exe`
-   - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition)
-     1. Open the repository root in the IDE
-     2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment.
-     3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task).
-
-### Subsequently
-
-1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again
-2. Follow step 3 above
+### Initial Setup
+
+#### 1. Clone the Repository
+Start by cloning this repository to your local machine.
+
+#### 2. Install Pre-requisites
+Ensure the following pre-requisites are installed and properly configured:
+
+- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/).
+- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later.
+
+#### 3. Bootstrap Your Local Environment
+Run the following commands within the project folder:
+
+- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+.
+- **Setup Project**: Execute `algokit project bootstrap all` to:
+  - Install dependencies and setup a Python virtual environment in `.venv`.
+  - Copy `.env.template` to `.env`.
+- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network.
+
+### Development Workflow
+
+#### Terminal
+Directly manage and interact with your project using AlgoKit commands:
+
+1. **Build Contracts**: `algokit project run build` compiles all smart contracts.
+2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network.
+
+#### VS Code 
+For a seamless experience with breakpoint debugging and other features:
+
+1. **Open Project**: In VS Code, open the repository root.
+2. **Install Extensions**: Follow prompts to install recommended extensions.
+3. **Debugging**:
+   - Use `F5` to start debugging.
+   - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run.
+
+#### JetBrains IDEs
+While primarily optimized for VS Code, JetBrains IDEs are supported:
+
+1. **Open Project**: In your JetBrains IDE, open the repository root.
+2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment.
+3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds.
+
+## AlgoKit Workspaces and Project Management
+This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace.
 
 > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder.### Continuous Integration / Continuous Deployment (CI/CD)
 

diff --git a/...contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-cd.yaml b/...contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-cd.yaml
@@ -31,7 +31,7 @@ jobs:
         run: pipx install algokit
 
       - name: Bootstrap dependencies
-        run: algokit bootstrap all --project-name 'production_beaker_smart_contract_typescript'
+        run: algokit project bootstrap all --project-name 'production_beaker_smart_contract_typescript'
 
       - name: Configure git
         shell: bash

diff --git a/...contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-ci.yaml b/...contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-ci.yaml
@@ -27,7 +27,7 @@ jobs:
         run: algokit localnet start
 
       - name: Bootstrap dependencies
-        run: algokit bootstrap all --project-name 'production_beaker_smart_contract_typescript'
+        run: algokit project bootstrap all --project-name 'production_beaker_smart_contract_typescript'
 
       - name: Configure git
         shell: bash

diff --git a/examples/generators/production_beaker_smart_contract_typescript/README.md b/examples/generators/production_beaker_smart_contract_typescript/README.md
@@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta
 
 > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension.
 
-### Initial setup
-
-1. Clone this repository locally
-2. Install pre-requisites:
-   - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine.
-   - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later.
-   - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will:
-     - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+
-     - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies
-     - Copy `.env.template` to `.env`
-   - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you.
-   - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`).
-3. Open the project and start debugging / developing via:
-   - Terminal
-     1. Run `algokit project run build` to build all contracts in the project
-     2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network.
-   - VS Code (Launch Configurations)
-     1. Open the repository root in VS Code
-     2. Install recommended extensions
-     3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging.
-        > **Note**
-        > If using Windows: Before running for the first time you will need to select the Python Interpreter.
-        1. Open the command palette (Ctrl/Cmd + Shift + P)
-        2. Search for `Python: Select Interpreter`
-        3. Select `./.venv/Scripts/python.exe`
-   - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition)
-     1. Open the repository root in the IDE
-     2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment.
-     3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task).
-
-### Subsequently
-
-1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again
-2. Follow step 3 above
+### Initial Setup
+
+#### 1. Clone the Repository
+Start by cloning this repository to your local machine.
+
+#### 2. Install Pre-requisites
+Ensure the following pre-requisites are installed and properly configured:
+
+- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/).
+- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later.
+
+#### 3. Bootstrap Your Local Environment
+Run the following commands within the project folder:
+
+- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+.
+- **Setup Project**: Execute `algokit project bootstrap all` to:
+  - Install dependencies and setup a Python virtual environment in `.venv`.
+  - Copy `.env.template` to `.env`.
+- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network.
+
+### Development Workflow
+
+#### Terminal
+Directly manage and interact with your project using AlgoKit commands:
+
+1. **Build Contracts**: `algokit project run build` compiles all smart contracts.
+2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network.
+
+#### VS Code 
+For a seamless experience with breakpoint debugging and other features:
+
+1. **Open Project**: In VS Code, open the repository root.
+2. **Install Extensions**: Follow prompts to install recommended extensions.
+3. **Debugging**:
+   - Use `F5` to start debugging.
+   - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run.
+
+#### JetBrains IDEs
+While primarily optimized for VS Code, JetBrains IDEs are supported:
+
+1. **Open Project**: In your JetBrains IDE, open the repository root.
+2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment.
+3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds.
+
+## AlgoKit Workspaces and Project Management
+This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace.
 
 > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder.### Continuous Integration / Continuous Deployment (CI/CD)
 

diff --git a/examples/generators/starter_beaker_smart_contract_python/README.md b/examples/generators/starter_beaker_smart_contract_python/README.md
@@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta
 
 > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension.
 
-### Initial setup
-
-1. Clone this repository locally
-2. Install pre-requisites:
-   - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine.
-   - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later.
-   - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will:
-     - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+
-     - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies
-     - Copy `.env.template` to `.env`
-   - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you.
-   - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`).
-3. Open the project and start debugging / developing via:
-   - Terminal
-     1. Run `algokit project run build` to build all contracts in the project
-     2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network.
-   - VS Code (Launch Configurations)
-     1. Open the repository root in VS Code
-     2. Install recommended extensions
-     3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging.
-        > **Note**
-        > If using Windows: Before running for the first time you will need to select the Python Interpreter.
-        1. Open the command palette (Ctrl/Cmd + Shift + P)
-        2. Search for `Python: Select Interpreter`
-        3. Select `./.venv/Scripts/python.exe`
-   - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition)
-     1. Open the repository root in the IDE
-     2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment.
-     3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task).
-
-### Subsequently
-
-1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again
-2. Follow step 3 above
+### Initial Setup
+
+#### 1. Clone the Repository
+Start by cloning this repository to your local machine.
+
+#### 2. Install Pre-requisites
+Ensure the following pre-requisites are installed and properly configured:
+
+- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/).
+- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later.
+
+#### 3. Bootstrap Your Local Environment
+Run the following commands within the project folder:
+
+- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+.
+- **Setup Project**: Execute `algokit project bootstrap all` to:
+  - Install dependencies and setup a Python virtual environment in `.venv`.
+  - Copy `.env.template` to `.env`.
+- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network.
+
+### Development Workflow
+
+#### Terminal
+Directly manage and interact with your project using AlgoKit commands:
+
+1. **Build Contracts**: `algokit project run build` compiles all smart contracts.
+2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network.
+
+#### VS Code 
+For a seamless experience with breakpoint debugging and other features:
+
+1. **Open Project**: In VS Code, open the repository root.
+2. **Install Extensions**: Follow prompts to install recommended extensions.
+3. **Debugging**:
+   - Use `F5` to start debugging.
+   - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run.
+
+#### JetBrains IDEs
+While primarily optimized for VS Code, JetBrains IDEs are supported:
+
+1. **Open Project**: In your JetBrains IDE, open the repository root.
+2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment.
+3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds.
+
+## AlgoKit Workspaces and Project Management
+This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace.
 
 > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder.