Skip to content

Commit

Permalink
chore: deprecating beaker; refreshing outdated docs (#559)
Browse files Browse the repository at this point in the history
* chore: deprecating beaker; refreshing outdated docs

* chore: refresh logo
  • Loading branch information
aorumbayev authored Aug 23, 2024
1 parent 41f5c7b commit f9b4c4d
Show file tree
Hide file tree
Showing 10 changed files with 21 additions and 34 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<div align="center">
<a href="https://github.com/algorandfoundation/algokit-cli"><img src="https://bafybeihfrtfg4vcufkcqmrtslkhx737ppz2fgn2lnctsd6waduqhhhibye.ipfs.nftstorage.link/" width=60%></a>
<a href="https://github.com/algorandfoundation/algokit-cli"><img src="https://ipfs.algonode.xyz/ipfs/QmZqt55wHXrZzhBihSVzXDvwp9rguvLAvFhUm1qJR6GYeQ" width=60%></a>
</div>

<p align="center">
Expand Down
2 changes: 1 addition & 1 deletion docs/cli/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -630,7 +630,7 @@ Name of an official template to use. To choose interactively, run this command w

* **Options**

tealscript | python | react | fullstack | beaker | base | playground
tealscript | python | react | fullstack | base | playground



Expand Down
10 changes: 5 additions & 5 deletions docs/features/generate.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ of available operations and parameters.
#### Python

```python
# A similar working example can be seen in the beaker_production template, when using Python deployment
# A similar working example can be seen in the algokit python template, when using Python deployment
from smart_contracts.artifacts.HelloWorldApp.client import (
HelloWorldAppClient,
)
Expand All @@ -66,7 +66,7 @@ response = app_client.hello(name="World")
#### TypeScript

```typescript
// A similar working example can be seen in the beaker_production template, when using TypeScript deployment
// A similar working example can be seen in the algokit python template with typescript deployer, when using TypeScript deployment
import { HelloWorldAppClient } from "./artifacts/HelloWorldApp/client";

const appClient = new HelloWorldAppClient(
Expand Down Expand Up @@ -104,7 +104,7 @@ Custom generate commands are defined in the `.algokit.toml` file within the proj

### Understanding `Generators`

A `generator` is essentially a compact, self-sufficient `copier` template. This template can optionally be defined within the primary `algokit templates` to offer supplementary functionality after a project is initialized from the template. For instance, the official [`algokit-beaker-default-template`](https://github.com/algorandfoundation/algokit-beaker-default-template/tree/main/template_content) provides a generator within the `.algokit/generators` directory. This generator can be employed for executing extra tasks on AlgoKit projects that have been initiated from this template, such as adding new smart contracts to an existing project. For a comprehensive explanation, please refer to the [`architecture decision record`](../architecture-decisions/2023-07-19_advanced_generate_command.md).
A `generator` is essentially a compact, self-sufficient `copier` template. This template can optionally be defined within the primary `algokit templates` to offer supplementary functionality after a project is initialized from the template. For instance, the official [`algokit-python-template`](https://github.com/algorandfoundation/algokit-python-template/tree/main/template_content) provides a generator within the `.algokit/generators` directory. This generator can be employed for executing extra tasks on AlgoKit projects that have been initiated from this template, such as adding new smart contracts to an existing project. For a comprehensive explanation, please refer to the [`architecture decision record`](../architecture-decisions/2023-07-19_advanced_generate_command.md).

### Requirements

Expand All @@ -130,7 +130,7 @@ The custom command employs the `copier` library to duplicate the files from the

### Examples

As an example, let's use the `smart-contract` generator from the `algokit-beaker-default-template` to add new contract to an existing project based on that template. The `smart-contract` generator is defined as follows:
As an example, let's use the `smart-contract` generator from the `algokit-python-template` to add new contract to an existing project based on that template. The `smart-contract` generator is defined as follows:

```toml
[algokit]
Expand Down Expand Up @@ -176,4 +176,4 @@ $ algokit generate smart-contract -a contract_name "MyCoolContract"

#### Third Party Generators

It is important to understand that by default, AlgoKit will always prompt you before executing a generator to ensure it's from a trusted source. If you are confident about the source of the generator, you can use the `--force` or `-f` option to execute the generator without this confirmation prompt. Be cautious while using this option and ensure the generator is from a trusted source. At the moment, a trusted source for a generator is defined as _a generator that is included in the official AlgoKit templates (e.g. `smart-contract` generator in `algokit-beaker-default-template`)_
It is important to understand that by default, AlgoKit will always prompt you before executing a generator to ensure it's from a trusted source. If you are confident about the source of the generator, you can use the `--force` or `-f` option to execute the generator without this confirmation prompt. Be cautious while using this option and ensure the generator is from a trusted source. At the moment, a trusted source for a generator is defined as _a generator that is included in the official AlgoKit templates (e.g. `smart-contract` generator in `algokit-python-template`)_
14 changes: 7 additions & 7 deletions docs/features/init.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ $ ~ algokit init
? Name of project / directory to create the project in: my-cool-app
```

Once above 2 questions are answered, the `cli` will start instantiating the project and will start asking questions specific to the template you are instantiating. By default official templates such as `python`, `fullstack`, `react`, `beaker` include a notion of a `preset`. If you want to skip all questions and let the tool preset the answers tailored for a starter project you can pick `Starter`, for a more advanced project that includes unit tests, CI automation and other advanced features, pick `Production`. Lastly, if you prefer to modify the experience and tailor the template to your needs, pick the `Custom` preset.
Once above 2 questions are answered, the `cli` will start instantiating the project and will start asking questions specific to the template you are instantiating. By default official templates such as `python`, `fullstack`, `react`, `python` include a notion of a `preset`. If you want to skip all questions and let the tool preset the answers tailored for a starter project you can pick `Starter`, for a more advanced project that includes unit tests, CI automation and other advanced features, pick `Production`. Lastly, if you prefer to modify the experience and tailor the template to your needs, pick the `Custom` preset.

If you want to accept the default for each option simply hit [enter] or alternatively to speed things up you can run `algokit init --defaults` and they will be auto-accepted.

Expand Down Expand Up @@ -60,7 +60,7 @@ Copying /Users/algokit/algokit-init/my-smart-contract/smart_contracts/.env.templ
🎉 Performed initial git commit successfully! 🎉
🙌 Project initialized at `my-smart-contract`! For template specific next steps, consult the documentation of your selected template 🧐
Your selected template comes from:
➡️ https://github.com/algorandfoundation/algokit-beaker-default-template
➡️ https://github.com/algorandfoundation/algokit-python-template
As a suggestion, if you wanted to open the project in VS Code you could execute:
> cd my-smart-contract && code .
Expand All @@ -79,11 +79,11 @@ There are a number of options that can be used to provide answers to the templat

As well as the official Algorand templates shown when running the init command, community templates can also be provided by providing a URL via the prompt or the `--template-url` option.

e.g. `algokit init --template-url https://github.com/algorandfoundation/algokit-beaker-default-template` (that being the url of the official beaker template, the same as `algokit init -t beaker`).
e.g. `algokit init --template-url https://github.com/algorandfoundation/algokit-python-template` (that being the url of the official python template, the same as `algokit init -t python`).

The `--template-url` option can be combined with `--template-url-ref` to specify a specific commit, branch or tag

e.g. `algokit init --template-url https://github.com/algorandfoundation/algokit-beaker-default-template --template-url-ref 9985005b7389c90c6afed685d75bb8e7608b2a96`
e.g. `algokit init --template-url https://github.com/algorandfoundation/algokit-python-template --template-url-ref 0232bb68a2f5628e910ee52f62bf13ded93fe672`

If the URL is not an official template there is a potential security risk and so to continue you must either acknowledge this prompt, or if you are in a non-interactive environment you can pass the `--UNSAFE-SECURITY-accept-template-url` option (but we generally don't recommend this option so users can review the warning message first) e.g.

Expand All @@ -101,18 +101,18 @@ If you want to create a community template, you can use the [AlgoKit guidelines

Answers to specific template prompts can be provided with the `--answer {key} {value}` option, which can be used multiple times for each prompt. Quotes can be used for values with spaces e.g. `--answer author_name "Algorand Foundation"`.

To find out the key for a specific answer you can either look at `.algokit/.copier-answers.yml` in the root folder of a project created via `algokit init` or in the `copier.yaml` file of a template repo e.g. for the [beaker template](https://github.com/algorandfoundation/algokit-beaker-default-template/blob/main/copier.yaml).
To find out the key for a specific answer you can either look at `.algokit/.copier-answers.yml` in the root folder of a project created via `algokit init` or in the `copier.yaml` file of a template repo e.g. for the [python template](https://github.com/algorandfoundation/algokit-python-template/blob/main/copier.yaml).

## Non-interactive project initialization

By combining a number of options, it is possible to initialize a new project without any interaction. For example, to create a project named `my-smart-contract` using the `beaker` template with no git, no bootstrapping, the author name of `Algorand Foundation`, and defaults for all other values, you could execute the following:
By combining a number of options, it is possible to initialize a new project without any interaction. For example, to create a project named `my-smart-contract` using the `python` template with no git, no bootstrapping, the author name of `Algorand Foundation`, and defaults for all other values, you could execute the following:

```
$ ~ algokit init -n my-smart-contract -t python --no-git --no-bootstrap --answer author_name "Algorand Foundation" --defaults
🙌 Project initialized at `my-smart-contract`! For template specific next steps, consult the documentation of your selected template 🧐
Your selected template comes from:
➡️ https://github.com/algorandfoundation/algokit-beaker-default-template
➡️ https://github.com/algorandfoundation/algokit-python-template
As a suggestion, if you wanted to open the project in VS Code you could execute:
> cd my-smart-contract && code .
Expand Down
16 changes: 6 additions & 10 deletions docs/tutorials/algokit-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This README serves as a guide on how to create custom templates for AlgoKit, a tool for initializing Algorand smart contract projects.
Creating templates in AlgoKit involves the use of various configuration files and a templating engine to generate project structures that are tailored to your needs.
This guide will cover the key concepts and best practices for creating templates in AlgoKit.
We will also refer to the official [`algokit-beaker-default-template`](https://github.com/algorandfoundation/algokit-beaker-default-template) as an example.
We will also refer to the official [`algokit-python-template`](https://github.com/algorandfoundation/algokit-python-template) as an example.

## Table of Contents

Expand All @@ -26,7 +26,7 @@ We will also refer to the official [`algokit-beaker-default-template`](https://g

For users who are keen on getting started with creating AlgoKit templates, you can follow these quick steps:

1. Click on `Use this template`->`Create a new repository` on [algokit-beaker-default-template](https://github.com/algorandfoundation/algokit-beaker-default-template) Github page. This will create a new reference repository with clean git history, allowing you to start modifying and transforming the base beaker template into your own custom template.
1. Click on `Use this template`->`Create a new repository` on [algokit-python-template](https://github.com/algorandfoundation/algokit-python-template) Github page. This will create a new reference repository with clean git history, allowing you to start modifying and transforming the base python template into your own custom template.
2. Modify the cloned template according to your specific needs. You can refer to the remainder of this tutorial for an understanding of expected behaviors from the AlgoKit side, Copier - the templating framework, and key concepts related to the default files you will encounter in the reference template.

## Overview of AlgoKit Templates
Expand All @@ -47,7 +47,7 @@ AlgoKit provides the `algokit init` command to initialize a new project using a

This file is the AlgoKit configuration file for this project which can be used to specify the minimum version of the AlgoKit. This is essential to ensure that projects created with your template are always compatible with the version of AlgoKit they are using.

Example from `algokit-beaker-default-template`:
Example from `algokit-python-template`:

```toml
[algokit]
Expand All @@ -61,7 +61,7 @@ This specifies that the template requires at least version `v1.1.0-beta.4` of Al
Python projects in AlgoKit can leverage a wide range of tools for dependency management and project configuration. While Poetry and the `pyproject.toml` file are common choices, they are not the only options.
If you opt to use Poetry, you'll rely on the pyproject.toml file to define the project's metadata and dependencies. This configuration file can utilize the Jinja templating syntax for customization.

Example snippet from `algokit-beaker-default-template`:
Example snippet from `algokit-python-template`:

```toml
[tool.poetry]
Expand All @@ -71,11 +71,7 @@ description = "Algorand smart contracts"
authors = ["{{ author_name }} <{{ author_email }}>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10"
beaker-pyteal = "^1.0.0"
algokit-utils = "^1.3"
python-dotenv = "^1.0.0"
...
```

This example shows how project metadata and dependencies are defined in `pyproject.toml`, using Jinja syntax to allow placeholders for project metadata.
Expand Down Expand Up @@ -176,7 +172,7 @@ python_path:

After mastering the use of `copier` and building your templates based on the official AlgoKit template repositories, you can enhance your proficiency by learning to define `custom generators`. Essentially, generators are smaller-scope `copier` templates designed to provide additional functionality after a project has been initialized from the template.

For example, the official [`algokit-beaker-default-template`](https://github.com/algorandfoundation/algokit-beaker-default-template/tree/main/template_content) incorporates a generator in the `.algokit/generators` directory. This generator can be utilized to execute auxiliary tasks on AlgoKit projects that are initiated from this template, like adding new smart contracts to an existing project. For a comprehensive understanding, please consult the [`architecture decision record`](../architecture-decisions/2023-07-19_advanced_generate_command.md) and [`algokit generate documentation`](../features/generate.md).
For example, the official [`algokit-python-template`](https://github.com/algorandfoundation/algokit-python-template/tree/main/template_content) incorporates a generator in the `.algokit/generators` directory. This generator can be utilized to execute auxiliary tasks on AlgoKit projects that are initiated from this template, like adding new smart contracts to an existing project. For a comprehensive understanding, please consult the [`architecture decision record`](../architecture-decisions/2023-07-19_advanced_generate_command.md) and [`algokit generate documentation`](../features/generate.md).

#### How to Create a Generator

Expand Down
2 changes: 1 addition & 1 deletion docs/tutorials/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ Once the `Algorand Python` based project is created, you can get started by buil

[![Watch the video](https://ipfs.algonode.xyz/ipfs/Qmc9mRaPoDyhUFmek4ETxVfKUKzUg9pf3Tss5xwkBGdQis)](https://ipfs.algonode.xyz/ipfs/Qma6gNqxsSFc9Jbh8kBTZyVLv5gqFj1xnrsjoeT6MAAwCw/)

The App ID of the deployed contract and its Algorand address is displayed, followed by the message returned from the smart contract call (`Hello, Beaker`).
The App ID of the deployed contract and its Algorand address is displayed, followed by the message returned from the smart contract call (`Hello, Python`).

1. Start LocalNet
2. Build the smart contract. Notice how a folder named `artifacts` is created with the [AVM (Algorand Virtual Machine)](https://developer.algorand.org/docs/get-details/dapps/avm/) related artifacts for deploying your smart contract.
Expand Down
6 changes: 0 additions & 6 deletions src/algokit/cli/init.py
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,6 @@ class ContractLanguage(Enum):

PYTHON = "Python 🐍"
TYPESCRIPT = "TypeScript 📘"
PYTEAL = "PyTeal 🔧"


class TemplateKey(str, Enum):
Expand Down Expand Up @@ -117,7 +116,6 @@ def __eq__(self, other: object) -> bool:
LANGUAGE_TO_TEMPLATE_MAP = {
ContractLanguage.PYTHON: TemplateKey.PYTHON,
ContractLanguage.TYPESCRIPT: TemplateKey.TEALSCRIPT,
ContractLanguage.PYTEAL: TemplateKey.BEAKER,
}


Expand All @@ -140,10 +138,6 @@ def _get_blessed_templates() -> dict[TemplateKey, BlessedTemplateSource]:
url="gh:algorandfoundation/algokit-fullstack-template",
description="Official template for starter or production fullstack applications.",
),
TemplateKey.BEAKER: BlessedTemplateSource(
url="gh:algorandfoundation/algokit-beaker-default-template",
description="Official template for starter or production Beaker applications.",
),
TemplateKey.BASE: BlessedTemplateSource(
url="gh:algorandfoundation/algokit-base-template",
description="Official base template for enforcing workspace structure for standalone AlgoKit projects.",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ DEBUG: selected project_type = Smart Contracts 📜
? Which language would you like to use for the smart contract?
Python 🐍
TypeScript 📘
PyTeal 🔧
DEBUG: selected language = ContractLanguage.PYTHON
DEBUG: template source = gh:robdmoore/copier-helloworld
DEBUG: Attempting to load project config from {current_working_directory}/.algokit.toml
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ DEBUG: selected project_type = Smart Contracts & DApp Frontend 🎛️
? Which language would you like to use for the smart contract?
Python 🐍
TypeScript 📘
PyTeal 🔧
DEBUG: selected language = ContractLanguage.PYTHON
DEBUG: template source = gh:robdmoore/copier-helloworld
DEBUG: Attempting to load project config from {current_working_directory}/.algokit.toml
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ DEBUG: selected project_type = Smart Contracts 📜
? Which language would you like to use for the smart contract?
Python 🐍
TypeScript 📘
PyTeal 🔧
DEBUG: selected language = ContractLanguage.PYTHON
DEBUG: template source = gh:robdmoore/copier-helloworld
DEBUG: Attempting to load project config from {current_working_directory}/.algokit.toml
Expand Down

1 comment on commit f9b4c4d

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coverage

Coverage Report
FileStmtsMissCoverMissing
src/algokit
   __init__.py15753%6–13, 17–24, 32–34
   __main__.py440%1–7
src/algokit/cli
   __init__.py47394%31–34
   codespace.py50982%28, 114, 137, 150–155
   completions.py108992%63–64, 83, 93–99
   dispenser.py121199%77
   doctor.py53394%146–148
   explore.py631576%35–40, 42–47, 85–92, 113
   generate.py70396%76–77, 155
   goal.py47198%79
   init.py3102492%491–492, 497–498, 501, 522, 525–527, 538, 542, 600, 626, 655, 688, 697–699, 702–707, 720, 739, 751–752
   localnet.py1523279%65, 86–113, 133–137, 170, 182, 197–207, 220, 271, 292–293
   task.py34391%25–28
src/algokit/cli/common
   utils.py37295%137, 139
src/algokit/cli/project
   bootstrap.py32197%33
   deploy.py1172083%47, 49, 102, 125, 147–149, 270, 277, 291–299, 302–311
   link.py891682%60, 65–66, 101–105, 115–120, 148–149, 218–219, 223
   list.py33585%21–23, 51–56
   run.py46296%38, 174
src/algokit/cli/tasks
   analyze.py81199%81
   assets.py821384%65–66, 72, 74–75, 105, 119, 125–126, 132, 134, 136–137
   ipfs.py51884%52, 80, 92, 94–95, 105–107
   mint.py1061586%51, 73, 100–103, 108, 113, 131–132, 158, 335–339
   send_transaction.py651085%52–53, 57, 89, 158, 170–174
   sign_transaction.py59886%21, 28–30, 71–72, 109, 123
   transfer.py39392%26, 90, 117
   utils.py1144660%29–37, 43–46, 78–79, 103–104, 128–136, 155–165, 212, 261–262, 282–293, 300–302, 324
   vanity_address.py561082%41, 45–48, 112, 114, 121–123
   wallet.py79495%21, 66, 136, 162
src/algokit/core
   codespace.py1756861%34–37, 41–44, 48–71, 111–112, 125–133, 191, 200–202, 210, 216–217, 229–236, 251–298, 311–313, 338–344, 348, 395
   conf.py57984%12, 24, 28, 36, 38, 73–75, 80
   dispenser.py2022687%91, 123–124, 141–149, 191–192, 198–200, 218–219, 259–260, 318, 332–334, 345–346, 356, 369, 384
   doctor.py65789%67–69, 92–94, 134
   generate.py50394%44, 85, 103
   goal.py65494%21, 36–37, 47
   init.py671085%53, 57–62, 70, 81, 88, 108–109
   log_handlers.py68790%50–51, 63, 112–116, 125
   proc.py45198%99
   sandbox.py2632391%32, 89–92, 97, 101–103, 153, 201–208, 219, 590, 606, 631, 639
   typed_client_generation.py1702088%62–64, 103–108, 132, 135–138, 156, 159–162, 229, 232–235
   utils.py1504073%50–51, 57–69, 125–131, 155, 158, 164–177, 206–208, 237–240, 262
src/algokit/core/compilers
   python.py28582%19–20, 25, 49–50
src/algokit/core/config_commands
   container_engine.py412149%24, 29–31, 47–76
   version_prompt.py921485%37–38, 68, 87–90, 108, 118–125, 148
src/algokit/core/project
   __init__.py53394%50, 86, 145
   bootstrap.py120893%47, 126–127, 149, 176, 207–209
   deploy.py69987%108–111, 120–122, 126, 131
   run.py1321390%83, 88, 97–98, 133–134, 138–139, 143, 147, 277–278, 293
src/algokit/core/tasks
   analyze.py93397%105–112, 187
   ipfs.py63789%58–64, 140, 144, 146, 152
   nfd.py491373%25, 31, 34–41, 70–72, 99–101
   vanity_address.py903462%49–50, 54, 59–75, 92–108, 128–131
   wallet.py71593%37, 129, 155–157
src/algokit/core/tasks/mint
   mint.py74988%123–133
   models.py921782%50, 52, 57, 71–74, 81–90
TOTAL475665786% 

Tests Skipped Failures Errors Time
499 0 💤 0 ❌ 0 🔥 27.734s ⏱️

Please sign in to comment.