diff --git a/.gitignore b/.gitignore index 744552e9e..f925c7536 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +.devportal +*.iml + # Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] @@ -172,6 +175,7 @@ cython_debug/ #Sphinx .doctrees/ +doctrees/ docs/cli/temp.md # Miscellaneous diff --git a/docs/architecture-decisions/2022-11-14_sandbox-approach.md b/docs/architecture-decisions/2022-11-14_sandbox-approach.md index 0658720dc..93735976c 100644 --- 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](../../docs/algokit.md#Guiding-Principles)** - specifically Seamless onramp, Leverage existing ecosystem, Meet devs where they are +- **[AlgoKit Guiding Principles](../index.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 index 9eb56b385..fc414a154 100644 --- 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](../../docs/algokit.md#Guiding-Principles) - specifically: +- [AlgoKit Guiding Principles](../index.md#guiding-principles) - specifically: - **Cohesive developer tool suite** - **Seamless onramp** - **Secure by default** diff --git a/docs/architecture-decisions/2023-06-06_frontend-templates.md b/docs/architecture-decisions/2023-06-06_frontend-templates.md index dbe6560fd..6bf4363ef 100644 --- a/docs/architecture-decisions/2023-06-06_frontend-templates.md +++ b/docs/architecture-decisions/2023-06-06_frontend-templates.md @@ -34,7 +34,7 @@ AlgoKit v2 aims provide an end-to-end development and deployment experience that - **Maintainability**: The dApp templating feature should be easy to maintain and extend. This implies that the feature should be implemented in a way that allows for easy addition of new templates and/or modification of existing ones as the complexity and variety of templates scale. - **Seamless onramp**: The dApp templating feature should provide a seamless onramp for developers to get started with dApp development. This implies that the feature should provide a simple and intuitive way to get started with dApp development and deployment. Providing developers a choice on whether they want more flexibility or rely on default recommended practices. -All of the aforementioned requirements should be met in a way that is consistent with the guiding principles of AlgoKit or attempt to find a balanced trade of between the principles that satisfies the requirements. Refer to [AlgoKit Guiding Principles](../../docs/algokit.md#Guiding-Principles) for detailed reference on the principles. +All of the aforementioned requirements should be met in a way that is consistent with the guiding principles of AlgoKit or attempt to find a balanced trade of between the principles that satisfies the requirements. Refer to [AlgoKit Guiding Principles](../index.md#guiding-principles) for detailed reference on the principles. ## Explored options diff --git a/docs/architecture-decisions/2023-07-19_advanced_generate_command.md b/docs/architecture-decisions/2023-07-19_advanced_generate_command.md index 1eb9d03be..b2865c039 100644 --- a/docs/architecture-decisions/2023-07-19_advanced_generate_command.md +++ b/docs/architecture-decisions/2023-07-19_advanced_generate_command.md @@ -36,7 +36,7 @@ This implies extension of existing starter guidelines available for template bui - **Maintainability**: The `advanced algokit generate` capabilities on `algokit-cli` and related artifacts on respective official templates should be easy to maintain and extend. - **Seamless onramp**: Great developer experience for template builders to create their own `generators` and user experience to use them via `advanced algokit generate` command should be a priority. -All of the aforementioned requirements should be met in a way that is consistent with the guiding principles of AlgoKit or attempt to find a balanced trade of between the principles that satisfies the requirements. Refer to [AlgoKit Guiding Principles](../../docs/algokit.md#Guiding-Principles) for detailed reference on the principles. +All of the aforementioned requirements should be met in a way that is consistent with the guiding principles of AlgoKit or attempt to find a balanced trade of between the principles that satisfies the requirements. Refer to [AlgoKit Guiding Principles](../index.md#guiding-principles) for detailed reference on the principles. ## Considered Options diff --git a/docs/sphinx/conf.py b/docs/cli/conf.py similarity index 100% rename from docs/sphinx/conf.py rename to docs/cli/conf.py diff --git a/docs/sphinx/index.rst b/docs/cli/index.rst similarity index 100% rename from docs/sphinx/index.rst rename to docs/cli/index.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..243a2bef9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,33 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +import os + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "AlgoKit" +copyright = "2023, Algorand Foundation" +author = "Algorand Foundation" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["myst_parser", "sphinx_starlight_builder", "sphinx_markdown_builder"] + +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "cli/index.rst"] + +myst_heading_anchors = 4 +markdown_http_base = "." +starlight_http_base = "/starlight" + +# TODO: Change based on env +# myst_enable_extensions = [ +# "substitution", +# ] +# myst_substitutions = { +# "README": "", +# "ARC1": "", +# "ARC32": "https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0032.md" +# } diff --git a/docs/features/completions.md b/docs/features/completions.md index 3cbf686a3..c65205833 100644 --- a/docs/features/completions.md +++ b/docs/features/completions.md @@ -30,7 +30,7 @@ To setup the completions, AlgoKit provides commands that will modify the current > **Note** > If you would prefer AlgoKit to not modify your interactive shell scripts you can install the completions yourself by following the instructions [here](https://click.palletsprojects.com/en/8.1.x/shell-completion/). -To [install](../cli/index.md#install) completions for the current shell execute `algokit completions install`. You should see output similar to below: +To [install](../reference.md#install) completions for the current shell execute `algokit completions install`. You should see output similar to below: ``` $ ~ algokit completions install @@ -42,7 +42,7 @@ After installing the completions don't forget to restart the shell to begin usin ## Uninstalling -To [uninstall](../cli/index.md#uninstall) completions for the current shell run `algokit completions uninstall`: +To [uninstall](../reference.md#uninstall) completions for the current shell run `algokit completions uninstall`: ``` $ ~ algokit completions uninstall @@ -51,6 +51,6 @@ AlgoKit completions uninstalled for zsh 🎉 ## Shell Option -To install/uninstall the completions for a specific [shell](../cli/index.md#shell) the `--shell` option can be used e.g. `algokit completions install --shell bash`. +To install/uninstall the completions for a specific [shell](../reference.md#--shell) the `--shell` option can be used e.g. `algokit completions install --shell bash`. -To learn more about the `algokit completions` command, please refer to [completions](../cli/index.md#completions) in the AlgoKit CLI reference documentation. +To learn more about the `algokit completions` command, please refer to [completions](../reference.md#completions) in the AlgoKit CLI reference documentation. diff --git a/docs/features/config.md b/docs/features/config.md index aaf7bd018..e839381b8 100644 --- a/docs/features/config.md +++ b/docs/features/config.md @@ -34,4 +34,4 @@ This command configures the container engine settings for AlgoKit. ## Further Reading -For in-depth details, visit the [configuration section](../cli/index.md#config) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [configuration section](../reference.md#config) in the AlgoKit CLI reference documentation. diff --git a/docs/features/dispenser.md b/docs/features/dispenser.md index 800816f88..96fdf9623 100644 --- a/docs/features/dispenser.md +++ b/docs/features/dispenser.md @@ -87,4 +87,4 @@ Options ## Further Reading -For in-depth details, visit the [dispenser section](../cli/index.md#dispenser) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [dispenser section](../reference.md#dispenser) in the AlgoKit CLI reference documentation. diff --git a/docs/features/doctor.md b/docs/features/doctor.md index da4dfb241..df4ba1a24 100644 --- a/docs/features/doctor.md +++ b/docs/features/doctor.md @@ -52,4 +52,4 @@ docker compose: 2.1.3 install via https://docs.docker.com/compose/install/ ``` -For more details about the `AlgoKit doctor` command, please refer to the [AlgoKit CLI reference documentation](../cli/index.md#doctor). +For more details about the `AlgoKit doctor` command, please refer to the [AlgoKit CLI reference documentation](../reference.md#doctor). diff --git a/docs/features/explore.md b/docs/features/explore.md index 6eff46e4f..e300c8fbd 100644 --- a/docs/features/explore.md +++ b/docs/features/explore.md @@ -1,6 +1,6 @@ # AlgoKit explore -AlgoKit provides a quick shortcut to [explore](../cli/index.md#explore) various Algorand networks using [lora](https://lora.algokit.io/) including [AlgoKit LocalNet](./localnet.md)! +AlgoKit provides a quick shortcut to [explore](../reference.md#explore) various Algorand networks using [lora](https://lora.algokit.io/) including [AlgoKit LocalNet](./localnet.md)! ## LocalNet @@ -18,4 +18,4 @@ The following three commands are all equivalent and will open lora pointing to t `algokit explore mainnet` will open lora pointing to MainNet via the [node](https://algonode.io/api/). -To learn more about the `algokit explore` command, please refer to [explore](../cli/index.md#explore) in the AlgoKit CLI reference documentation. +To learn more about the `algokit explore` command, please refer to [explore](../reference.md#explore) in the AlgoKit CLI reference documentation. diff --git a/docs/features/generate.md b/docs/features/generate.md index 7e3a81ace..36c3245a4 100644 --- a/docs/features/generate.md +++ b/docs/features/generate.md @@ -1,10 +1,10 @@ # AlgoKit Generate -The `algokit generate` [command](../cli/index.md#generate) is used to generate components used in an AlgoKit project. It also allows for custom generate commands which are loaded from the .algokit.toml file in your project directory. +The `algokit generate` [command](../reference.md#generate) is used to generate components used in an AlgoKit project. It also allows for custom generate commands which are loaded from the .algokit.toml file in your project directory. ## 1. Typed clients -The `algokit generate client` [command](../cli/index.md#client) can be used to generate a typed client from an [ARC-0032](https://arc.algorand.foundation/ARCs/arc-0032) or [ARC-0056](https://github.com/algorandfoundation/ARCs/pull/258) application specification with both Python and TypeScript available as target languages. +The `algokit generate client` [command](../reference.md#client) can be used to generate a typed client from an [ARC-0032](https://arc.algorand.foundation/ARCs/arc-0032) or [ARC-0056](https://github.com/algorandfoundation/ARCs/pull/258) application specification with both Python and TypeScript available as target languages. ### Prerequisites @@ -22,7 +22,7 @@ You can either specify a path to an ARC-0032 JSON file, an ARC-0056 JSON file or The output path is interpreted as relative to the current working directory, however an absolute path may also be specified e.g. `algokit generate client application.json --output /absolute/path/to/client.py` -There are two tokens available for use with the `-o`, `--output` [option](../cli/index.md#-o---output-): +There are two tokens available for use with the `-o`, `--output` [option](../reference.md#-o---output-): - `{contract_name}`: This will resolve to a name based on the ARC-0032/ARC-0056 contract name, formatted appropriately for the target language. - `{app_spec_dir}`: This will resolve to the parent directory of the `application.json`, `*.arc32.json`, `*.arc56.json` file which can be useful to output a client relative to its source file. diff --git a/docs/features/goal.md b/docs/features/goal.md index 58f1c7c21..54d2c31e5 100644 --- a/docs/features/goal.md +++ b/docs/features/goal.md @@ -136,4 +136,4 @@ Would you like to see it now? (Y/n): n This is particularly useful when you know a command will require user input, such as creating new accounts, importing keys, or signing transactions. -For more details about the `AlgoKit goal` command, please refer to the [AlgoKit CLI reference documentation](../cli/index.md#goal). +For more details about the `AlgoKit goal` command, please refer to the [AlgoKit CLI reference documentation](../reference.md#goal). diff --git a/docs/features/init.md b/docs/features/init.md index 66fff0e97..9d3cb90fd 100644 --- a/docs/features/init.md +++ b/docs/features/init.md @@ -1,6 +1,6 @@ # AlgoKit Init -The `algokit init` [command](../cli/index.md#init) is used to quickly initialize new projects using official Algorand Templates or community provided templates. It supports a fully guided command line wizard experience, as well as fully scriptable / non-interactive functionality via command options. +The `algokit init` [command](../reference.md#init) is used to quickly initialize new projects using official Algorand Templates or community provided templates. It supports a fully guided command line wizard experience, as well as fully scriptable / non-interactive functionality via command options. ## Quick start @@ -36,7 +36,7 @@ For more details on workspaces and standalone projects, refer to the [AlgoKit Pr ## Bootstrapping -You will also be prompted if you wish to run the [bootstrap](../cli/index.md#bootstrap) command, this is useful if you plan to immediately begin developing in the new project. If you passed in `--defaults` or `--bootstrap` then it will automatically run bootstrapping unless you passed in `--no-bootstrap`. +You will also be prompted if you wish to run the [bootstrap](../reference.md#bootstrap) command, this is useful if you plan to immediately begin developing in the new project. If you passed in `--defaults` or `--bootstrap` then it will automatically run bootstrapping unless you passed in `--no-bootstrap`. ``` @@ -73,7 +73,7 @@ After bootstrapping you are also given the opportunity to initialize a git repo, ## Options -There are a number of options that can be used to provide answers to the template prompts. Some of the options requiring further explanation are detailed below, but consult the CLI reference for all available [options](../cli/index.md#init). +There are a number of options that can be used to provide answers to the template prompts. Some of the options requiring further explanation are detailed below, but consult the CLI reference for all available [options](../reference.md#init). ## Community Templates @@ -119,4 +119,4 @@ As a suggestion, if you wanted to open the project in VS Code you could execute: ``` -For more details about the `AlgoKit init` command, please refer to the [AlgoKit CLI reference documentation](../cli/index.md#init). +For more details about the `AlgoKit init` command, please refer to the [AlgoKit CLI reference documentation](../reference.md#init). diff --git a/docs/features/localnet.md b/docs/features/localnet.md index 5e89f13dc..045624cf4 100644 --- a/docs/features/localnet.md +++ b/docs/features/localnet.md @@ -6,7 +6,7 @@ AlgoKit LocalNet uses Docker images that are optimised for a great dev experienc The philosophy we take with AlgoKit LocalNet is that you should treat it as an ephemeral network. This means assume it could be reset at any time - don't store data on there that you can't recover / recreate. We have optimised the AlgoKit LocalNet experience to minimise situations where the network will get reset to improve the experience, but it can and will still happen in a number of situations. -> For details on executing `algokit localnet` without `docker` or `podman` refer to the [codespaces](#codespaces) section. +> For details on executing `algokit localnet` without `docker` or `podman` refer to the [codespaces](#github-codespaces-based-localnet) section. ## Prerequisites @@ -164,7 +164,7 @@ AlgoKit Utils provides methods to help you do this: - TypeScript - [`ensureFunded`](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/transfer.md#ensurefunded) and [`getDispenserAccount`](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/transfer.md#dispenser) - Python - [`ensure_funded`](https://algorandfoundation.github.io/algokit-utils-py/html/apidocs/algokit_utils/algokit_utils.html#algokit_utils.ensure_funded) and [`get_dispenser_account`](https://algorandfoundation.github.io/algokit-utils-py/html/apidocs/algokit_utils/algokit_utils.html#algokit_utils.get_dispenser_account) -For more details about the `AlgoKit localnet` command, please refer to the [AlgoKit CLI reference documentation](../cli/index.md#localnet). +For more details about the `AlgoKit localnet` command, please refer to the [AlgoKit CLI reference documentation](../reference.md#localnet). ## GitHub Codespaces-based LocalNet @@ -186,6 +186,6 @@ Running an interactive session ensures that you have control over the lifecycle - `-r`, `--repo-url`: The URL of the repository to use. Defaults to the AlgoKit base template repository (`algorandfoundation/algokit-base-template`). The reason why algokit-base-template is used by default is due to [.devcontainer.json](https://github.com/algorandfoundation/algokit-base-template/blob/main/template_content/.devcontainer.json) which defines the scripts that take care of setting up AlgoKit CLI during container start. You can use any custom repo as a base, however it's important to ensure the reference [.devcontainer.json](https://github.com/algorandfoundation/algokit-base-template/blob/main/template_content/.devcontainer.json) file exists in your repository **otherwise there will be no ports to forward from the codespace**. - `--force`, `-f`: Force deletes stale codespaces and skips confirmation prompts. Defaults to explicitly prompting for confirmation. -For more details about managing LocalNet in GitHub Codespaces, please refer to the [AlgoKit CLI reference documentation](../cli/index.md#codespace). +For more details about managing LocalNet in GitHub Codespaces, please refer to the [AlgoKit CLI reference documentation](../reference.md#codespace). > Tip: By specifying alternative port values it is possible to have several LocalNet instances running where one is using default ports via `algokit localnet start` with Docker | Podman and the other relies on port forwarding via `algokit localnet codespace`. diff --git a/docs/features/project.md b/docs/features/project.md index bd987f648..3fab8eba1 100644 --- a/docs/features/project.md +++ b/docs/features/project.md @@ -1,6 +1,6 @@ # AlgoKit Project -`algokit project` is a collection of commands and command groups useful for managing algokit compliant [project workspaces](./init.md#workspaces). +`algokit project` is a collection of commands and command groups useful for managing algokit compliant [project workspaces](./init.md#workspaces-vs-standalone-projects). ## Overview diff --git a/docs/features/project/bootstrap.md b/docs/features/project/bootstrap.md index e06252671..25008d901 100644 --- a/docs/features/project/bootstrap.md +++ b/docs/features/project/bootstrap.md @@ -2,7 +2,7 @@ The AlgoKit Project Bootstrap feature allows you to bootstrap different project dependencies by looking up specific files in your current directory and immediate sub directories by convention. -This is useful to allow for expedited initial setup for each developer e.g. when they clone a repository for the first time. It's also useful to provide a quick getting started experience when initialising a new project via [AlgoKit Init](./init.md) and meeting our goal of "nothing to debugging code in 5 minutes". +This is useful to allow for expedited initial setup for each developer e.g. when they clone a repository for the first time. It's also useful to provide a quick getting started experience when initialising a new project via [AlgoKit Init](../init.md) and meeting our goal of "nothing to debugging code in 5 minutes". It can bootstrap one or all of the following (with other options potentially being added in the future): @@ -111,11 +111,11 @@ poetry: Installing the current project: algokit (0.1.0) ### Bootstrap all -Execute `algokit project bootstrap all` to initiate `algokit project bootstrap env`, `algokit project bootstrap npm`, and `algokit project bootstrap poetry` commands within the current directory and all its immediate sub-directories. This comprehensive command is automatically triggered following the initialization of a new project through the [AlgoKit Init](./init.md) command. +Execute `algokit project bootstrap all` to initiate `algokit project bootstrap env`, `algokit project bootstrap npm`, and `algokit project bootstrap poetry` commands within the current directory and all its immediate sub-directories. This comprehensive command is automatically triggered following the initialization of a new project through the [AlgoKit Init](../init.md) command. #### Filtering Options -The `algokit project bootstrap all` command includes flags for more granular control over the bootstrapping process within [AlgoKit workspaces](../init.md#workspaces): +The `algokit project bootstrap all` command includes flags for more granular control over the bootstrapping process within [AlgoKit workspaces](../init.md#workspaces-vs-standalone-projects): - `--project-name`: This flag allows you to specify one or more project names to bootstrap. Only projects matching the provided names will be bootstrapped. This is particularly useful in monorepos or when working with multiple projects in the same directory structure. @@ -125,4 +125,4 @@ These new flags enhance the flexibility and efficiency of the bootstrapping proc ## Further Reading -To learn more about the `algokit project bootstrap` command, please refer to [bootstrap](../../cli/index.md#bootstrap) in the AlgoKit CLI reference documentation. +To learn more about the `algokit project bootstrap` command, please refer to [bootstrap](../../reference.md#bootstrap) in the AlgoKit CLI reference documentation. diff --git a/docs/features/project/deploy.md b/docs/features/project/deploy.md index 859938d6a..dce371890 100644 --- a/docs/features/project/deploy.md +++ b/docs/features/project/deploy.md @@ -208,4 +208,4 @@ This example shows how to deploy smart contracts to the testnet using a custom d ## Further Reading -For in-depth details, visit the [deploy](../../cli/index.md#deploy) section in the AlgoKit CLI reference documentation. +For in-depth details, visit the [deploy](../../reference.md#deploy) section in the AlgoKit CLI reference documentation. diff --git a/docs/features/project/link.md b/docs/features/project/link.md index 08bf89097..cc0bd10bf 100644 --- a/docs/features/project/link.md +++ b/docs/features/project/link.md @@ -64,4 +64,4 @@ This command will generate TypeScript clients for all contract projects and plac ## Further Reading -To learn more about the `algokit project link` command, please refer to [link](../../cli/index.md#link) in the AlgoKit CLI reference documentation. +To learn more about the `algokit project link` command, please refer to [link](../../reference.md#link) in the AlgoKit CLI reference documentation. diff --git a/docs/features/project/list.md b/docs/features/project/list.md index 0f8275363..2bd10a5a9 100644 --- a/docs/features/project/list.md +++ b/docs/features/project/list.md @@ -40,4 +40,4 @@ This message indicates that either the current directory does not contain a `.al ## Further Reading -To learn more about the `algokit project list` command, please refer to [list](../../cli/index.md#list) in the AlgoKit CLI reference documentation. +To learn more about the `algokit project list` command, please refer to [list](../../reference.md#list) in the AlgoKit CLI reference documentation. diff --git a/docs/features/project/run.md b/docs/features/project/run.md index a6031e288..a77cfa9a2 100644 --- a/docs/features/project/run.md +++ b/docs/features/project/run.md @@ -181,4 +181,4 @@ In this example, if the `hello` command in `.algokit.toml` is defined as `echo " ## Further Reading -To learn more about the `algokit project run` command, please refer to [run](../../cli/index.md#run) in the AlgoKit CLI reference documentation. +To learn more about the `algokit project run` command, please refer to [run](../../reference.md#run) in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/ipfs.md b/docs/features/tasks/ipfs.md index 638038be3..0b6dcf3a8 100644 --- a/docs/features/tasks/ipfs.md +++ b/docs/features/tasks/ipfs.md @@ -63,4 +63,4 @@ Please note, the maximum file size that can be uploaded is 100MB. If you try to ## Further Reading -For in-depth details, visit the [ipfs section](../../cli/index.md#ipfs) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [ipfs section](../../reference.md#ipfs) in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/mint.md b/docs/features/tasks/mint.md index 5fabda32b..5ba650c42 100644 --- a/docs/features/tasks/mint.md +++ b/docs/features/tasks/mint.md @@ -67,4 +67,4 @@ For non interactive mode, refer to usage section above for available options. ## Further Reading -For in-depth details, visit the [mint section](../../cli/index.md#mint) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [mint section](../../reference.md#mint) in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/nfd.md b/docs/features/tasks/nfd.md index 813146151..2399af2cb 100644 --- a/docs/features/tasks/nfd.md +++ b/docs/features/tasks/nfd.md @@ -42,4 +42,4 @@ If the lookup is successful, the result will be output to the console in a JSON ## Further Reading -For in-depth details, visit the [nfd-lookup section](../../cli/index.md#nfd-lookup) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [nfd-lookup section](../../reference.md#nfd-lookup) in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/opt.md b/docs/features/tasks/opt.md index afc5785fb..2ebfa739f 100644 --- a/docs/features/tasks/opt.md +++ b/docs/features/tasks/opt.md @@ -68,4 +68,4 @@ $ algokit task opt-out --account {YOUR_ACCOUNT} --all ## Further Reading -For in-depth details, visit the [opt-in](../../cli/index.md#opt-in) and [opt-out](../../cli/index#opt-out) sections in the AlgoKit CLI reference documentation. +For in-depth details, visit the [opt-in](#opt-in) and [opt-out](#opt-out) sections in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/send.md b/docs/features/tasks/send.md index c9c5bf34b..ab6e3fa90 100644 --- a/docs/features/tasks/send.md +++ b/docs/features/tasks/send.md @@ -57,4 +57,4 @@ Please note, at the moment this feature only supports [`goal clerk`](https://dev ## Further Reading -For in-depth details, visit the [send section](../../cli/index.md#send) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [send section](../../reference.md#send) in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/sign.md b/docs/features/tasks/sign.md index 5c5e7bc9b..968b73bd3 100644 --- a/docs/features/tasks/sign.md +++ b/docs/features/tasks/sign.md @@ -91,4 +91,4 @@ Buffer.from(algosdk.encodeObj({ txn: txn.get_obj_for_encoding() })).toString( ## Further Reading -For in-depth details, visit the [sign section](../../cli/index.md#sign) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [sign section](../../reference.md#sign) in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/transfer.md b/docs/features/tasks/transfer.md index 4e5034d43..7a1151ad2 100644 --- a/docs/features/tasks/transfer.md +++ b/docs/features/tasks/transfer.md @@ -51,4 +51,4 @@ By default: ## Further Reading -For in-depth details, visit the [transfer section](../../cli/index.md#transfer) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [transfer section](../../reference.md#transfer) in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/vanity_address.md b/docs/features/tasks/vanity_address.md index d8d9c3609..57ec9c202 100644 --- a/docs/features/tasks/vanity_address.md +++ b/docs/features/tasks/vanity_address.md @@ -53,4 +53,4 @@ $ ~ algokit task vanity-address ALGO -o alias -a my-vanity-address ## Further Reading -For in-depth details, visit the [vanity-address section](../../cli/index.md#vanity-address) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [vanity-address section](../../reference.md#vanity-address) in the AlgoKit CLI reference documentation. diff --git a/docs/features/tasks/wallet.md b/docs/features/tasks/wallet.md index e77fa8c05..3cd561d2a 100644 --- a/docs/features/tasks/wallet.md +++ b/docs/features/tasks/wallet.md @@ -94,4 +94,4 @@ WSL2 environments don't have a keyring backend installed by default. If you want ## Further Reading -For in-depth details, visit the [wallet section](../../cli/index.md#wallet) in the AlgoKit CLI reference documentation. +For in-depth details, visit the [wallet section](../../reference.md#wallet) in the AlgoKit CLI reference documentation. diff --git a/docs/algokit.md b/docs/index.md similarity index 96% rename from docs/algokit.md rename to docs/index.md index 429c1dabb..9936d3895 100644 --- a/docs/algokit.md +++ b/docs/index.md @@ -27,9 +27,9 @@ AlgoKit has a number of global options that can impact all commands. Note: these - `-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/index.md#version-prompt) with `algokit config version-prompt disable`. +- `--skip-version-check` Skips updated AlgoKit version checking and prompting for that execution, this can also be disabled [permanently on a given machine](./reference.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. +See also the [AlgoKit CLI Reference](./index.md), which details every command, sub-command and option. ## AlgoKit Tutorials diff --git a/docs/cli/index.md b/docs/reference.md similarity index 69% rename from docs/cli/index.md rename to docs/reference.md index d7385368d..66d1bc5d0 100644 --- a/docs/cli/index.md +++ b/docs/reference.md @@ -1,251 +1,6 @@ # AlgoKit CLI Reference Documentation -- [algokit](#algokit) - - [Options](#options) - - [--version](#--version) - - [-v, --verbose](#-v---verbose) - - [--color, --no-color](#--color---no-color) - - [--skip-version-check](#--skip-version-check) - - [compile](#compile) - - [Options](#options-1) - - [-v, --version ](#-v---version-) - - [py](#py) - - [Arguments](#arguments) - - [PUYAPY_ARGS](#puyapy_args) - - [python](#python) - - [Arguments](#arguments-1) - - [PUYAPY_ARGS](#puyapy_args-1) - - [ts](#ts) - - [Arguments](#arguments-2) - - [PUYATS_ARGS](#puyats_args) - - [typescript](#typescript) - - [Arguments](#arguments-3) - - [PUYATS_ARGS](#puyats_args-1) - - [completions](#completions) - - [install](#install) - - [Options](#options-2) - - [--shell ](#--shell-) - - [uninstall](#uninstall) - - [Options](#options-3) - - [--shell ](#--shell--1) - - [config](#config) - - [container-engine](#container-engine) - - [Options](#options-4) - - [-f, --force](#-f---force) - - [Arguments](#arguments-4) - - [ENGINE](#engine) - - [version-prompt](#version-prompt) - - [Arguments](#arguments-5) - - [ENABLE](#enable) - - [dispenser](#dispenser) - - [fund](#fund) - - [Options](#options-5) - - [-r, --receiver ](#-r---receiver-) - - [-a, --amount ](#-a---amount-) - - [--whole-units](#--whole-units) - - [limit](#limit) - - [Options](#options-6) - - [--whole-units](#--whole-units-1) - - [login](#login) - - [Options](#options-7) - - [--ci](#--ci) - - [-o, --output ](#-o---output-) - - [-f, --file ](#-f---file-) - - [logout](#logout) - - [refund](#refund) - - [Options](#options-8) - - [-t, --txID ](#-t---txid-) - - [doctor](#doctor) - - [Options](#options-9) - - [-c, --copy-to-clipboard](#-c---copy-to-clipboard) - - [explore](#explore) - - [Arguments](#arguments-6) - - [NETWORK](#network) - - [generate](#generate) - - [client](#client) - - [Options](#options-10) - - [-o, --output ](#-o---output--1) - - [-l, --language ](#-l---language-) - - [-v, --version ](#-v---version--1) - - [Arguments](#arguments-7) - - [APP_SPEC_PATH_OR_DIR](#app_spec_path_or_dir) - - [goal](#goal) - - [Options](#options-11) - - [--console](#--console) - - [--interactive](#--interactive) - - [Arguments](#arguments-8) - - [GOAL_ARGS](#goal_args) - - [init](#init) - - [Options](#options-12) - - [-n, --name ](#-n---name-) - - [-t, --template ](#-t---template-) - - [--template-url ](#--template-url-) - - [--template-url-ref ](#--template-url-ref-) - - [--UNSAFE-SECURITY-accept-template-url](#--unsafe-security-accept-template-url) - - [--git, --no-git](#--git---no-git) - - [--defaults](#--defaults) - - [--bootstrap, --no-bootstrap](#--bootstrap---no-bootstrap) - - [--ide, --no-ide](#--ide---no-ide) - - [--workspace, --no-workspace](#--workspace---no-workspace) - - [-a, --answer ](#-a---answer--) - - [localnet](#localnet) - - [codespace](#codespace) - - [Options](#options-13) - - [-m, --machine ](#-m---machine-) - - [-a, --algod-port ](#-a---algod-port-) - - [-i, --indexer-port ](#-i---indexer-port-) - - [-k, --kmd-port ](#-k---kmd-port-) - - [-n, --codespace-name ](#-n---codespace-name-) - - [-r, --repo-url ](#-r---repo-url-) - - [-t, --timeout ](#-t---timeout-) - - [-f, --force](#-f---force-1) - - [config](#config-1) - - [Options](#options-14) - - [-f, --force](#-f---force-2) - - [Arguments](#arguments-9) - - [ENGINE](#engine-1) - - [console](#console) - - [explore](#explore-1) - - [logs](#logs) - - [Options](#options-15) - - [--follow, -f](#--follow--f) - - [--tail ](#--tail-) - - [reset](#reset) - - [Options](#options-16) - - [--update, --no-update](#--update---no-update) - - [-P, --config-dir ](#-p---config-dir-) - - [start](#start) - - [Options](#options-17) - - [-n, --name ](#-n---name--1) - - [-P, --config-dir ](#-p---config-dir--1) - - [-d, --dev, --no-dev](#-d---dev---no-dev) - - [--force](#--force) - - [status](#status) - - [stop](#stop) - - [project](#project) - - [bootstrap](#bootstrap) - - [Options](#options-18) - - [--force](#--force-1) - - [Options](#options-19) - - [--interactive, --no-ci, --non-interactive, --ci](#--interactive---no-ci---non-interactive---ci) - - [-p, --project-name ](#-p---project-name-) - - [-t, --type ](#-t---type-) - - [Options](#options-20) - - [--interactive, --non-interactive, --ci](#--interactive---non-interactive---ci) - - [Options](#options-21) - - [--ci, --no-ci](#--ci---no-ci) - - [deploy](#deploy) - - [Options](#options-22) - - [-C, -c, --command ](#-c--c---command-) - - [--interactive, --non-interactive, --ci](#--interactive---non-interactive---ci-1) - - [-P, --path ](#-p---path-) - - [--deployer ](#--deployer-) - - [--dispenser ](#--dispenser-) - - [-p, --project-name ](#-p---project-name--1) - - [Arguments](#arguments-10) - - [ENVIRONMENT_NAME](#environment_name) - - [EXTRA_ARGS](#extra_args) - - [link](#link) - - [Options](#options-23) - - [-p, --project-name ](#-p---project-name--2) - - [-l, --language ](#-l---language--1) - - [-a, --all](#-a---all) - - [-f, --fail-fast](#-f---fail-fast) - - [-v, --version ](#-v---version--2) - - [list](#list) - - [Arguments](#arguments-11) - - [WORKSPACE_PATH](#workspace_path) - - [run](#run) - - [task](#task) - - [analyze](#analyze) - - [Options](#options-24) - - [-r, --recursive](#-r---recursive) - - [--force](#--force-2) - - [--diff](#--diff) - - [-o, --output ](#-o---output--2) - - [-e, --exclude ](#-e---exclude-) - - [Arguments](#arguments-12) - - [INPUT_PATHS](#input_paths) - - [ipfs](#ipfs) - - [Options](#options-25) - - [-f, --file ](#-f---file--1) - - [-n, --name ](#-n---name--2) - - [mint](#mint) - - [Options](#options-26) - - [--creator ](#--creator-) - - [--name ](#--name-) - - [-u, --unit ](#-u---unit-) - - [-t, --total ](#-t---total-) - - [-d, --decimals ](#-d---decimals-) - - [--nft, --ft](#--nft---ft) - - [-i, --image ](#-i---image-) - - [-m, --metadata ](#-m---metadata-) - - [--mutable, --immutable](#--mutable---immutable) - - [-n, --network ](#-n---network-) - - [nfd-lookup](#nfd-lookup) - - [Options](#options-27) - - [-o, --output ](#-o---output--3) - - [Arguments](#arguments-13) - - [VALUE](#value) - - [opt-in](#opt-in) - - [Options](#options-28) - - [-a, --account ](#-a---account-) - - [-n, --network ](#-n---network--1) - - [Arguments](#arguments-14) - - [ASSET_IDS](#asset_ids) - - [opt-out](#opt-out) - - [Options](#options-29) - - [-a, --account ](#-a---account--1) - - [--all](#--all) - - [-n, --network ](#-n---network--2) - - [Arguments](#arguments-15) - - [ASSET_IDS](#asset_ids-1) - - [send](#send) - - [Options](#options-30) - - [-f, --file ](#-f---file--2) - - [-t, --transaction ](#-t---transaction-) - - [-n, --network ](#-n---network--3) - - [sign](#sign) - - [Options](#options-31) - - [-a, --account ](#-a---account--2) - - [-f, --file ](#-f---file--3) - - [-t, --transaction ](#-t---transaction--1) - - [-o, --output ](#-o---output--4) - - [--force](#--force-3) - - [transfer](#transfer) - - [Options](#options-32) - - [-s, --sender ](#-s---sender-) - - [-r, --receiver ](#-r---receiver--1) - - [--asset, --id ](#--asset---id-) - - [-a, --amount ](#-a---amount--1) - - [--whole-units](#--whole-units-2) - - [-n, --network ](#-n---network--4) - - [vanity-address](#vanity-address) - - [Options](#options-33) - - [-m, --match ](#-m---match-) - - [-o, --output ](#-o---output--5) - - [-a, --alias ](#-a---alias-) - - [--file-path ](#--file-path-) - - [-f, --force](#-f---force-3) - - [Arguments](#arguments-16) - - [KEYWORD](#keyword) - - [wallet](#wallet) - - [Options](#options-34) - - [-a, --address ](#-a---address-) - - [-m, --mnemonic](#-m---mnemonic) - - [-f, --force](#-f---force-4) - - [Arguments](#arguments-17) - - [ALIAS_NAME](#alias_name) - - [Arguments](#arguments-18) - - [ALIAS](#alias) - - [Options](#options-35) - - [-f, --force](#-f---force-5) - - [Arguments](#arguments-19) - - [ALIAS](#alias-1) - - [Options](#options-36) - - [-f, --force](#-f---force-6) - # algokit AlgoKit is your one-stop shop to develop applications on the Algorand blockchain. @@ -258,20 +13,20 @@ algokit [OPTIONS] COMMAND [ARGS]... ### Options - ### --version -Show the version and exit. +Show the version and exit. ### -v, --verbose -Enable logging of DEBUG messages to the console. +Enable logging of DEBUG messages to the console. ### --color, --no-color -Force enable or disable of console output styling. +Force enable or disable of console output styling. ### --skip-version-check + Skip version checking and prompting. ## compile @@ -285,8 +40,8 @@ algokit compile [OPTIONS] COMMAND [ARGS]... ### Options - ### -v, --version + The compiler version to pin to, for example, 1.0.0. If no version is specified, AlgoKit checks if the compiler is installed and runs the installed version. If the compiler is not installed, AlgoKit runs the latest version. If a version is specified, AlgoKit checks if an installed version matches and runs the installed version. Otherwise, AlgoKit runs the specified version. ### py @@ -299,8 +54,8 @@ algokit compile py [OPTIONS] [PUYAPY_ARGS]... ### Arguments - ### PUYAPY_ARGS + Optional argument(s) ### python @@ -313,8 +68,8 @@ algokit compile python [OPTIONS] [PUYAPY_ARGS]... ### Arguments - ### PUYAPY_ARGS + Optional argument(s) ### ts @@ -327,8 +82,8 @@ algokit compile ts [OPTIONS] [PUYATS_ARGS]... ### Arguments - ### PUYATS_ARGS + Optional argument(s) ### typescript @@ -341,8 +96,8 @@ algokit compile typescript [OPTIONS] [PUYATS_ARGS]... ### Arguments - ### PUYATS_ARGS + Optional argument(s) ## completions @@ -356,7 +111,7 @@ algokit completions [OPTIONS] COMMAND [ARGS]... ### install Install shell completions, this command will attempt to update the interactive profile script -for the current shell to support algokit completions. To specify a specific shell use --shell. +for the current shell to support algokit completions. To specify a specific shell use –shell. ```shell algokit completions install [OPTIONS] @@ -364,21 +119,18 @@ algokit completions install [OPTIONS] ### Options - ### --shell -Specify shell to install algokit completions for. - -* **Options** - - bash | zsh +Specify shell to install algokit completions for. +* **Options:** + bash | zsh ### uninstall Uninstall shell completions, this command will attempt to update the interactive profile script for the current shell to remove any algokit completions that have been added. -To specify a specific shell use --shell. +To specify a specific shell use –shell. ```shell algokit completions uninstall [OPTIONS] @@ -386,15 +138,12 @@ algokit completions uninstall [OPTIONS] ### Options - ### --shell -Specify shell to install algokit completions for. - -* **Options** - - bash | zsh +Specify shell to install algokit completions for. +* **Options:** + bash | zsh ## config @@ -414,14 +163,14 @@ algokit config container-engine [OPTIONS] [[docker|podman]] ### Options - ### -f, --force -Skip confirmation prompts. Defaults to 'yes' to all prompts. -### Arguments +Skip confirmation prompts. Defaults to ‘yes’ to all prompts. +### Arguments ### ENGINE + Optional argument ### version-prompt @@ -430,7 +179,7 @@ Controls whether AlgoKit checks and prompts for new versions. Set to [disable] to prevent AlgoKit performing this check permanently, or [enable] to resume checking. If no argument is provided then outputs current setting. -Also see --skip-version-check which can be used to disable check for a single command. +Also see –skip-version-check which can be used to disable check for a single command. ```shell algokit config version-prompt [OPTIONS] [[enable|disable]] @@ -438,8 +187,8 @@ algokit config version-prompt [OPTIONS] [[enable|disable]] ### Arguments - ### ENABLE + Optional argument ## dispenser @@ -460,16 +209,16 @@ algokit dispenser fund [OPTIONS] ### Options - ### -r, --receiver -**Required** Address or alias of the receiver to fund with TestNet ALGOs. +**Required** Address or alias of the receiver to fund with TestNet ALGOs. ### -a, --amount -**Required** Amount to fund. Defaults to microAlgos. +**Required** Amount to fund. Defaults to microAlgos. ### --whole-units + Use whole units (Algos) instead of smallest divisible units (microAlgos). Disabled by default. ### limit @@ -482,8 +231,8 @@ algokit dispenser limit [OPTIONS] ### Options - ### --whole-units + Use whole units (Algos) instead of smallest divisible units (microAlgos). Disabled by default. ### login @@ -496,23 +245,20 @@ algokit dispenser login [OPTIONS] ### Options - ### --ci -Generate an access token for CI. Issued for 30 days. +Generate an access token for CI. Issued for 30 days. ### -o, --output -Choose the output method for the access token. Defaults to stdout. Only applicable when --ci flag is set. - - -* **Options** - - stdout | file +Choose the output method for the access token. Defaults to stdout. Only applicable when –ci flag is set. +* **Options:** + stdout | file ### -f, --file -Output filename where you want to store the generated access token.Defaults to algokit_ci_token.txt. Only applicable when --ci flag is set and --output mode is file. + +Output filename where you want to store the generated access token.Defaults to algokit_ci_token.txt. Only applicable when –ci flag is set and –output mode is file. ### logout @@ -532,8 +278,8 @@ algokit dispenser refund [OPTIONS] ### Options - ### -t, --txID + **Required** Transaction ID of your refund operation. ## doctor @@ -549,8 +295,8 @@ algokit doctor [OPTIONS] ### Options - ### -c, --copy-to-clipboard + Copy the contents of the doctor message (in Markdown format) in your clipboard. ## explore @@ -563,8 +309,8 @@ algokit explore [OPTIONS] [[localnet|testnet|mainnet]] ### Arguments - ### NETWORK + Optional argument ## generate @@ -580,7 +326,7 @@ algokit generate [OPTIONS] COMMAND [ARGS]... Create a typed ApplicationClient from an ARC-32/56 application.json Supply the path to an application specification file or a directory to recursively search -for "application.json" files +for “application.json” files ```shell algokit generate client [OPTIONS] APP_SPEC_PATH_OR_DIR @@ -588,28 +334,25 @@ algokit generate client [OPTIONS] APP_SPEC_PATH_OR_DIR ### Options - ### -o, --output -Path to the output file. The following tokens can be used to substitute into the output path: {contract_name}, {app_spec_dir} +Path to the output file. The following tokens can be used to substitute into the output path: {contract_name}, {app_spec_dir} ### -l, --language -Programming language of the generated client code - - -* **Options** - - python | typescript +Programming language of the generated client code +* **Options:** + python | typescript ### -v, --version + The client generator version to pin to, for example, 1.0.0. If no version is specified, AlgoKit checks if the client generator is installed and runs the installed version. If the client generator is not installed, AlgoKit runs the latest version. If a version is specified, AlgoKit checks if an installed version matches and runs the installed version. Otherwise, AlgoKit runs the specified version. ### Arguments - ### APP_SPEC_PATH_OR_DIR + Required argument ## goal @@ -624,18 +367,18 @@ algokit goal [OPTIONS] [GOAL_ARGS]... ### Options - ### --console -Open a Bash console so you can execute multiple goal commands and/or interact with a filesystem. +Open a Bash console so you can execute multiple goal commands and/or interact with a filesystem. ### --interactive + Force running the goal command in interactive mode. ### Arguments - ### GOAL_ARGS + Optional argument(s) ## init @@ -652,9 +395,9 @@ automatically open Visual Studio Code. This should be run in the parent directory that you want the project folder created in. -By default, the --workspace flag creates projects within a workspace structure or integrates them into an existing +By default, the –workspace flag creates projects within a workspace structure or integrates them into an existing one, promoting organized management of multiple projects. Alternatively, -to disable this behavior use the --no-workspace flag, which ensures +to disable this behavior use the –no-workspace flag, which ensures the new project is created in a standalone target directory. This is suitable for isolated projects or when workspace integration is unnecessary. @@ -664,54 +407,51 @@ algokit init [OPTIONS] ### Options - ### -n, --name -Name of the project / directory / repository to create. +Name of the project / directory / repository to create. ### -t, --template -Name of an official template to use. To choose interactively, run this command with no arguments. - - -* **Options** - - tealscript | typescript | python | react | fullstack | base +Name of an official template to use. To choose interactively, run this command with no arguments. +* **Options:** + tealscript | typescript | python | react | fullstack | base ### --template-url -URL to a git repo with a custom project template. +URL to a git repo with a custom project template. ### --template-url-ref -Specific tag, branch or commit to use on git repo specified with --template-url. Defaults to latest. +Specific tag, branch or commit to use on git repo specified with –template-url. Defaults to latest. ### --UNSAFE-SECURITY-accept-template-url -Accept the specified template URL, acknowledging the security implications of arbitrary code execution trusting an unofficial template. +Accept the specified template URL, acknowledging the security implications of arbitrary code execution trusting an unofficial template. ### --git, --no-git -Initialise git repository in directory after creation. +Initialise git repository in directory after creation. ### --defaults -Automatically choose default answers without asking when creating this template. +Automatically choose default answers without asking when creating this template. ### --bootstrap, --no-bootstrap -Whether to run algokit project bootstrap to install and configure the new project's dependencies locally. +Whether to run algokit project bootstrap to install and configure the new project’s dependencies locally. ### --ide, --no-ide -Whether to open an IDE for you if the IDE and IDE config are detected. Supported IDEs: VS Code. +Whether to open an IDE for you if the IDE and IDE config are detected. Supported IDEs: VS Code. ### --workspace, --no-workspace -Whether to prefer structuring standalone projects as part of a workspace. An AlgoKit workspace is a conventional project structure that allows managing multiple standalone projects in a monorepo. +Whether to prefer structuring standalone projects as part of a workspace. An AlgoKit workspace is a conventional project structure that allows managing multiple standalone projects in a monorepo. ### -a, --answer + Answers key/value pairs to pass to the template. ## localnet @@ -732,42 +472,39 @@ algokit localnet codespace [OPTIONS] ### Options - ### -m, --machine -The GitHub Codespace machine type to use. Defaults to base tier. - - -* **Options** - - basicLinux32gb | standardLinux32gb | premiumLinux | largePremiumLinux +The GitHub Codespace machine type to use. Defaults to base tier. +* **Options:** + basicLinux32gb | standardLinux32gb | premiumLinux | largePremiumLinux ### -a, --algod-port -The port for the Algorand daemon. Defaults to 4001. +The port for the Algorand daemon. Defaults to 4001. ### -i, --indexer-port -The port for the Algorand indexer. Defaults to 8980. +The port for the Algorand indexer. Defaults to 8980. ### -k, --kmd-port -The port for the Algorand kmd. Defaults to 4002. +The port for the Algorand kmd. Defaults to 4002. ### -n, --codespace-name -The name of the codespace. Defaults to 'algokit-localnet_timestamp'. +The name of the codespace. Defaults to ‘algokit-localnet_timestamp’. ### -r, --repo-url -The URL of the repository. Defaults to algokit base template repo. +The URL of the repository. Defaults to algokit base template repo. ### -t, --timeout -Default max runtime timeout in minutes. Upon hitting the timeout a codespace will be shutdown to prevent accidental spending over GitHub Codespaces quota. Defaults to 4 hours. +Default max runtime timeout in minutes. Upon hitting the timeout a codespace will be shutdown to prevent accidental spending over GitHub Codespaces quota. Defaults to 4 hours. ### -f, --force + Force delete previously used codespaces with {CODESPACE_NAME_PREFIX}\* name prefix and skip prompts. Defaults to explicitly prompting for confirmation. ### config @@ -780,14 +517,14 @@ algokit localnet config [OPTIONS] [[docker|podman]] ### Options - ### -f, --force -Skip confirmation prompts. Defaults to 'yes' to all prompts. -### Arguments +Skip confirmation prompts. Defaults to ‘yes’ to all prompts. +### Arguments ### ENGINE + Optional argument ### console @@ -816,19 +553,16 @@ algokit localnet logs [OPTIONS] ### Options - ### --follow, -f -Follow log output. +Follow log output. ### --tail -Number of lines to show from the end of the logs for each container. - - -* **Default** - `all` +Number of lines to show from the end of the logs for each container. +* **Default:** + `all` ### reset @@ -840,12 +574,12 @@ algokit localnet reset [OPTIONS] ### Options - ### --update, --no-update -Enable or disable updating to the latest available LocalNet version, default: don't update +Enable or disable updating to the latest available LocalNet version, default: don’t update ### -P, --config-dir + Specify the custom localnet configuration directory. ### start @@ -858,21 +592,21 @@ algokit localnet start [OPTIONS] ### Options - ### -n, --name -Specify a name for a custom LocalNet instance. AlgoKit will not manage the configuration of named LocalNet instances, allowing developers to configure it in any way they need. Defaults to 'sandbox'. +Specify a name for a custom LocalNet instance. AlgoKit will not manage the configuration of named LocalNet instances, allowing developers to configure it in any way they need. Defaults to ‘sandbox’. ### -P, --config-dir -Specify the custom localnet configuration directory. Defaults to '~/.config' on UNIX and 'C:\\Users\\USERNAME\\AppData\\Roaming' on Windows. +Specify the custom localnet configuration directory. Defaults to ‘~/.config’ on UNIX and ‘C:\\Users\\USERNAME\\AppData\\Roaming’ on Windows. ### -d, --dev, --no-dev -Control whether to launch 'algod' in developer mode or not. Defaults to 'yes'. +Control whether to launch ‘algod’ in developer mode or not. Defaults to ‘yes’. ### --force -Ignore the prompt to stop the LocalNet if it's already running. + +Ignore the prompt to stop the LocalNet if it’s already running. ### status @@ -911,8 +645,8 @@ algokit project bootstrap [OPTIONS] COMMAND [ARGS]... ### Options - ### --force + Continue even if minimum AlgoKit version is not met #### all @@ -925,23 +659,20 @@ algokit project bootstrap all [OPTIONS] ### Options - ### --interactive, --no-ci, --non-interactive, --ci -Enable/disable interactive prompts. If the CI environment variable is set, defaults to non-interactive +Enable/disable interactive prompts. If the CI environment variable is set, defaults to non-interactive ### -p, --project-name -(Optional) Projects to execute the command on. Defaults to all projects found in the current directory. +(Optional) Projects to execute the command on. Defaults to all projects found in the current directory. ### -t, --type -(Optional) Limit execution to specific project types if executing from workspace. - -* **Options** - - ProjectType.FRONTEND | ProjectType.CONTRACT | ProjectType.BACKEND +(Optional) Limit execution to specific project types if executing from workspace. +* **Options:** + ProjectType.FRONTEND | ProjectType.CONTRACT | ProjectType.BACKEND #### env @@ -953,8 +684,8 @@ algokit project bootstrap env [OPTIONS] ### Options - ### --interactive, --non-interactive, --ci + Enable/disable interactive prompts. If the CI environment variable is set, defaults to non-interactive #### npm @@ -967,9 +698,9 @@ algokit project bootstrap npm [OPTIONS] ### Options - ### --ci, --no-ci -Run 'npm ci' instead of 'npm install' in CI mode (clean install). + +Run ‘npm ci’ instead of ‘npm install’ in CI mode (clean install). #### poetry @@ -989,44 +720,44 @@ algokit project deploy [OPTIONS] [ENVIRONMENT_NAME] [EXTRA_ARGS]... ### Options - ### -C, -c, --command -Custom deploy command. If not provided, will load the deploy command from .algokit.toml file. +Custom deploy command. If not provided, will load the deploy command from .algokit.toml file. ### --interactive, --non-interactive, --ci -Enable/disable interactive prompts. Defaults to non-interactive if the CI environment variable is set. Interactive MainNet deployments prompt for confirmation. +Enable/disable interactive prompts. Defaults to non-interactive if the CI environment variable is set. Interactive MainNet deployments prompt for confirmation. ### -P, --path -Specify the project directory. If not provided, current working directory will be used. +Specify the project directory. If not provided, current working directory will be used. ### --deployer -(Optional) Alias of the deployer account. Otherwise, will prompt the deployer mnemonic if specified in .algokit.toml file. +(Optional) Alias of the deployer account. Otherwise, will prompt the deployer mnemonic if specified in .algokit.toml file. ### --dispenser -(Optional) Alias of the dispenser account. Otherwise, will prompt the dispenser mnemonic if specified in .algokit.toml file. +(Optional) Alias of the dispenser account. Otherwise, will prompt the dispenser mnemonic if specified in .algokit.toml file. ### -p, --project-name + (Optional) Projects to execute the command on. Defaults to all projects found in the current directory. Option is mutually exclusive with command. ### Arguments - ### ENVIRONMENT_NAME -Optional argument +Optional argument ### EXTRA_ARGS + Optional argument(s) ### link -Automatically invoke 'algokit generate client' on contract projects available in the workspace. -Must be invoked from the root of a standalone 'frontend' typed project. +Automatically invoke ‘algokit generate client’ on contract projects available in the workspace. +Must be invoked from the root of a standalone ‘frontend’ typed project. ```shell algokit project link [OPTIONS] @@ -1034,30 +765,27 @@ algokit project link [OPTIONS] ### Options - ### -p, --project-name -Specify contract projects for the command. Defaults to all in the current workspace. +Specify contract projects for the command. Defaults to all in the current workspace. ### -l, --language -Programming language of the generated client code - - -* **Options** - - python | typescript +Programming language of the generated client code +* **Options:** + python | typescript ### -a, --all -Link all contract projects with the frontend project Option is mutually exclusive with project_name. +Link all contract projects with the frontend project Option is mutually exclusive with project_name. ### -f, --fail-fast -Exit immediately if at least one client generation process fails +Exit immediately if at least one client generation process fails ### -v, --version + The client generator version to pin to, for example, 1.0.0. If no version is specified, AlgoKit checks if the client generator is installed and runs the installed version. If the client generator is not installed, AlgoKit runs the latest version. If a version is specified, AlgoKit checks if an installed version matches and runs the installed version. Otherwise, AlgoKit runs the specified version. ### list @@ -1070,8 +798,8 @@ algokit project list [OPTIONS] [WORKSPACE_PATH] ### Arguments - ### WORKSPACE_PATH + Optional argument ### run @@ -1100,30 +828,30 @@ algokit task analyze [OPTIONS] INPUT_PATHS... ### Options - ### -r, --recursive -Recursively search for all TEAL files within the provided directory. +Recursively search for all TEAL files within the provided directory. ### --force -Force verification without the disclaimer confirmation prompt. +Force verification without the disclaimer confirmation prompt. ### --diff -Exit with a non-zero code if differences are found between current and last reports. Reports are generated each run, but with this flag execution fails if the current report doesn't match the last report. Reports are stored in the .algokit/static-analysis/snapshots folder by default. Use --output for a custom path. +Exit with a non-zero code if differences are found between current and last reports. Reports are generated each run, but with this flag execution fails if the current report doesn’t match the last report. Reports are stored in the .algokit/static-analysis/snapshots folder by default. Use –output for a custom path. ### -o, --output -Directory path where to store the results of the static analysis. Defaults to .algokit/static-analysis/snapshots. +Directory path where to store the results of the static analysis. Defaults to .algokit/static-analysis/snapshots. ### -e, --exclude + Exclude specific vulnerabilities from the analysis. Supports multiple exclusions in a single run. ### Arguments - ### INPUT_PATHS + Required argument(s) ### ipfs @@ -1160,12 +888,12 @@ algokit task ipfs upload [OPTIONS] ### Options - ### -f, --file -**Required** Path to the file to upload. +**Required** Path to the file to upload. ### -n, --name + Human readable name for this upload, for use in file listings. ### mint @@ -1178,54 +906,51 @@ algokit task mint [OPTIONS] ### Options - ### --creator -**Required** Address or alias of the asset creator. +**Required** Address or alias of the asset creator. ### --name -Asset name. +Asset name. ### -u, --unit -**Required** Unit name of the asset. +**Required** Unit name of the asset. ### -t, --total -Total supply of the asset. Defaults to 1. +Total supply of the asset. Defaults to 1. ### -d, --decimals -Number of decimals. Defaults to 0. +Number of decimals. Defaults to 0. ### --nft, --ft + Whether the asset should be validated as NFT or FT. Refers to NFT by default and validates canonical definitions of pure or fractional NFTs as per ARC3 standard. - ### -i, --image -**Required** Path to the asset image file to be uploaded to IPFS. +**Required** Path to the asset image file to be uploaded to IPFS. ### -m, --metadata + Path to the ARC19 compliant asset metadata file to be uploaded to IPFS. If not provided, a default metadata object will be generated automatically based on asset-name, decimals and image. For more details refer to [https://arc.algorand.foundation/ARCs/arc-0003#json-metadata-file-schema](https://arc.algorand.foundation/ARCs/arc-0003#json-metadata-file-schema). - ### --mutable, --immutable -Whether the asset should be mutable or immutable. Refers to ARC19 by default. +Whether the asset should be mutable or immutable. Refers to ARC19 by default. ### -n, --network -Network to use. Refers to localnet by default. - -* **Options** - - localnet | testnet | mainnet +Network to use. Refers to localnet by default. +* **Options:** + localnet | testnet | mainnet ### nfd-lookup @@ -1237,20 +962,17 @@ algokit task nfd-lookup [OPTIONS] VALUE ### Options - ### -o, --output -Output format for NFD API response. Defaults to address|domain resolved. - -* **Options** - - full | tiny | address +Output format for NFD API response. Defaults to address|domain resolved. +* **Options:** + full | tiny | address ### Arguments - ### VALUE + Required argument ### opt-in @@ -1263,24 +985,21 @@ algokit task opt-in [OPTIONS] ASSET_IDS... ### Options - ### -a, --account -**Required** Address or alias of the signer account. +**Required** Address or alias of the signer account. ### -n, --network -Network to use. Refers to localnet by default. - -* **Options** - - localnet | testnet | mainnet +Network to use. Refers to localnet by default. +* **Options:** + localnet | testnet | mainnet ### Arguments - ### ASSET_IDS + Required argument(s) ### opt-out @@ -1293,28 +1012,25 @@ algokit task opt-out [OPTIONS] [ASSET_IDS]... ### Options - ### -a, --account -**Required** Address or alias of the signer account. +**Required** Address or alias of the signer account. ### --all -Opt-out of all assets with zero balance. +Opt-out of all assets with zero balance. ### -n, --network -Network to use. Refers to localnet by default. - - -* **Options** - localnet | testnet | mainnet +Network to use. Refers to localnet by default. +* **Options:** + localnet | testnet | mainnet ### Arguments - ### ASSET_IDS + Optional argument(s) ### send @@ -1327,23 +1043,20 @@ algokit task send [OPTIONS] ### Options - ### -f, --file -Single or multiple message pack encoded signed transactions from binary file to send. Option is mutually exclusive with transaction. +Single or multiple message pack encoded signed transactions from binary file to send. Option is mutually exclusive with transaction. ### -t, --transaction -Base64 encoded signed transaction to send. Option is mutually exclusive with file. +Base64 encoded signed transaction to send. Option is mutually exclusive with file. ### -n, --network -Network to use. Refers to localnet by default. - - -* **Options** - localnet | testnet | mainnet +Network to use. Refers to localnet by default. +* **Options:** + localnet | testnet | mainnet ### sign @@ -1355,24 +1068,24 @@ algokit task sign [OPTIONS] ### Options - ### -a, --account -**Required** Address or alias of the signer account. +**Required** Address or alias of the signer account. ### -f, --file -Single or multiple message pack encoded transactions from binary file to sign. Option is mutually exclusive with transaction. +Single or multiple message pack encoded transactions from binary file to sign. Option is mutually exclusive with transaction. ### -t, --transaction -Single base64 encoded transaction object to sign. Option is mutually exclusive with file. +Single base64 encoded transaction object to sign. Option is mutually exclusive with file. ### -o, --output -The output file path to store signed transaction(s). +The output file path to store signed transaction(s). ### --force + Force signing without confirmation. ### transfer @@ -1385,35 +1098,32 @@ algokit task transfer [OPTIONS] ### Options - ### -s, --sender -**Required** Address or alias of the sender account. +**Required** Address or alias of the sender account. ### -r, --receiver -**Required** Address or alias to an account that will receive the asset(s). +**Required** Address or alias to an account that will receive the asset(s). ### --asset, --id -Asset ID to transfer. Defaults to 0 (Algo). +Asset ID to transfer. Defaults to 0 (Algo). ### -a, --amount -**Required** Amount to transfer. +**Required** Amount to transfer. ### --whole-units -Use whole units (Algos | ASAs) instead of smallest divisible units (for example, microAlgos). Disabled by default. +Use whole units (Algos | ASAs) instead of smallest divisible units (for example, microAlgos). Disabled by default. ### -n, --network -Network to use. Refers to localnet by default. - -* **Options** - - localnet | testnet | mainnet +Network to use. Refers to localnet by default. +* **Options:** + localnet | testnet | mainnet ### vanity-address @@ -1428,42 +1138,36 @@ algokit task vanity-address [OPTIONS] KEYWORD ### Options - ### -m, --match -Location where the keyword will be included. Default is start. - - -* **Options** - - start | anywhere | end +Location where the keyword will be included. Default is start. +* **Options:** + start | anywhere | end ### -o, --output -How the output will be presented. - - -* **Options** - - stdout | alias | file +How the output will be presented. +* **Options:** + stdout | alias | file ### -a, --alias -Alias for the address. Required if output is "alias". +Alias for the address. Required if output is “alias”. ### --file-path -File path where to dump the output. Required if output is "file". +File path where to dump the output. Required if output is “file”. ### -f, --force -Allow overwriting an aliases without confirmation, if output option is 'alias'. -### Arguments +Allow overwriting an aliases without confirmation, if output option is ‘alias’. +### Arguments ### KEYWORD + Required argument ### wallet @@ -1484,22 +1188,22 @@ algokit task wallet add [OPTIONS] ALIAS_NAME ### Options - ### -a, --address
-**Required** The address of the account. +**Required** The address of the account. ### -m, --mnemonic -If specified then prompt the user for a mnemonic phrase interactively using masked input. +If specified then prompt the user for a mnemonic phrase interactively using masked input. ### -f, --force + Allow overwriting an existing alias. ### Arguments - ### ALIAS_NAME + Required argument #### get @@ -1512,8 +1216,8 @@ algokit task wallet get [OPTIONS] ALIAS ### Arguments - ### ALIAS + Required argument #### list @@ -1534,14 +1238,14 @@ algokit task wallet remove [OPTIONS] ALIAS ### Options - ### -f, --force + Allow removing an alias without confirmation. ### Arguments - ### ALIAS + Required argument #### reset @@ -1554,6 +1258,6 @@ algokit task wallet reset [OPTIONS] ### Options - ### -f, --force + Allow removing all aliases without confirmation. diff --git a/docs/tutorials/algokit-template.md b/docs/tutorials/algokit-template.md index ed86d7762..4d4a76fba 100644 --- a/docs/tutorials/algokit-template.md +++ b/docs/tutorials/algokit-template.md @@ -18,7 +18,7 @@ We will also refer to the official [`algokit-python-template`](https://github.co - [Bootstrap Option](#bootstrap-option) - [Predefined Copier Answers](#predefined-copier-answers) - [Default Behaviors](#default-behaviors) - - [Generators](#generators) + - [Generators](#working-with-generators) - [Recommendations](#recommendations) - [Conclusion](#conclusion) @@ -211,7 +211,7 @@ This should dynamically load and display your generator as an optional `cli` com - **Versioning**: Use `.algokit.toml` to specify the minimum compatible version of AlgoKit. - **Testing**: Include test configurations and scripts in your templates to encourage testing best practices. - **Linting and Formatting**: Integrate linters and code formatters in your templates to ensure code quality. -- **Algokit Principle**: for details on generic principles on designing templates refer to [algokit design principles](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md#guiding-principles). +- **Algokit Principle**: for details on generic principles on designing templates refer to [algokit design principles](../index.md#guiding-principles). ## Conclusion diff --git a/docs/tutorials/intro.md b/docs/tutorials/intro.md index 40808695a..75e991d8f 100644 --- a/docs/tutorials/intro.md +++ b/docs/tutorials/intro.md @@ -86,8 +86,10 @@ Once finished, (if you have it installed) VS Code should automatically be opened ![AlgoKit Playground Contract](../imgs/algokitplayground.png) +(algokit-project-structure)= ## AlgoKit Project structure 🏗 + The structure of your fresh algokit project instance will look similar to below: ```bash @@ -162,7 +164,7 @@ This will then deploy to your LocalNet instance and display the same output as i We have only covered a tiny fraction of the capabilities of the AlgoKit CLI and its related ecosystem of templates and utilities for an efficient developer experience. -- To get the most out of `AlgoKit`, we recommend to get started with learning more about AlgoKit and what you can do with it by checking out our extensive [AlgoKit CLI documentation](../algokit.md). +- To get the most out of `AlgoKit`, we recommend to get started with learning more about AlgoKit and what you can do with it by checking out our extensive [AlgoKit CLI documentation](../index.md). - Explore the `README.md` files at the root of any project created via `algokit init`. All official AlgoKit templates include detailed quick started guides, an interactive code tour and various presets which can be customized to your needs. - To learn more about `Algorand Python`, take a look at the [documentation](https://algorandfoundation.github.io/puya/). - To learn more about the commands demonstrated in this tutorial, refer to [`init`](../features/init.md) and [`project`](../features/project.md) to get a comprehensive understanding of their further capabilities. diff --git a/docs/tutorials/smart-contracts.md b/docs/tutorials/smart-contracts.md index 786587a39..dc8ce9a63 100644 --- a/docs/tutorials/smart-contracts.md +++ b/docs/tutorials/smart-contracts.md @@ -1,5 +1,9 @@ # Smart Contract Tutorial +```{warning} +This is a work in progress! +``` + _TODO_ [mental model image] diff --git a/poetry.lock b/poetry.lock index 8ff4288bd..352fd2f93 100644 --- a/poetry.lock +++ b/poetry.lock @@ -862,17 +862,6 @@ files = [ {file = "h11-0.14.0.tar.gz", hash = "sha256:8f19fbbe99e72420ff35c00b27a34cb9937e902a8b810e2c88300c6f0a3b699d"}, ] -[[package]] -name = "html2text" -version = "2024.2.26" -description = "Turn HTML into equivalent Markdown-structured text." -optional = false -python-versions = ">=3.8" -groups = ["dev"] -files = [ - {file = "html2text-2024.2.26.tar.gz", hash = "sha256:05f8e367d15aaabc96415376776cdd11afd5127a77fce6e36afc60c563ca2c32"}, -] - [[package]] name = "html5lib" version = "1.1" @@ -1317,6 +1306,26 @@ files = [ {file = "MarkupSafe-2.1.5.tar.gz", hash = "sha256:d283d37a890ba4c1ae73ffadf8046435c76e7bc2247bbb63c00bd1a709c6544b"}, ] +[[package]] +name = "mdit-py-plugins" +version = "0.4.2" +description = "Collection of plugins for markdown-it-py" +optional = false +python-versions = ">=3.8" +groups = ["dev"] +files = [ + {file = "mdit_py_plugins-0.4.2-py3-none-any.whl", hash = "sha256:0c673c3f889399a33b95e88d2f0d111b4447bdfea7f237dab2d488f459835636"}, + {file = "mdit_py_plugins-0.4.2.tar.gz", hash = "sha256:5f2cd1fdb606ddf152d37ec30e46101a60512bc0e5fa1a7002c36647b09e26b5"}, +] + +[package.dependencies] +markdown-it-py = ">=1.0.0,<4.0.0" + +[package.extras] +code-style = ["pre-commit"] +rtd = ["myst-parser", "sphinx-book-theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] + [[package]] name = "mdurl" version = "0.1.2" @@ -1549,6 +1558,33 @@ files = [ {file = "mypy_extensions-1.0.0.tar.gz", hash = "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782"}, ] +[[package]] +name = "myst-parser" +version = "4.0.1" +description = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser," +optional = false +python-versions = ">=3.10" +groups = ["dev"] +files = [ + {file = "myst_parser-4.0.1-py3-none-any.whl", hash = "sha256:9134e88959ec3b5780aedf8a99680ea242869d012e8821db3126d427edc9c95d"}, + {file = "myst_parser-4.0.1.tar.gz", hash = "sha256:5cfea715e4f3574138aecbf7d54132296bfd72bb614d31168f48c477a830a7c4"}, +] + +[package.dependencies] +docutils = ">=0.19,<0.22" +jinja2 = "*" +markdown-it-py = ">=3.0,<4.0" +mdit-py-plugins = ">=0.4.1,<1.0" +pyyaml = "*" +sphinx = ">=7,<9" + +[package.extras] +code-style = ["pre-commit (>=4.0,<5.0)"] +linkify = ["linkify-it-py (>=2.0,<3.0)"] +rtd = ["ipython", "sphinx (>=7)", "sphinx-autodoc2 (>=0.5.0,<0.6.0)", "sphinx-book-theme (>=1.1,<2.0)", "sphinx-copybutton", "sphinx-design", "sphinx-pyscript", "sphinx-tippy (>=0.4.3)", "sphinx-togglebutton", "sphinxext-opengraph (>=0.9.0,<0.10.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"] +testing = ["beautifulsoup4", "coverage[toml]", "defusedxml", "pygments (<2.19)", "pytest (>=8,<9)", "pytest-cov", "pytest-param-files (>=0.6.0,<0.7.0)", "pytest-regressions", "sphinx-pytest"] +testing-docutils = ["pygments", "pytest (>=8,<9)", "pytest-param-files (>=0.6.0,<0.7.0)"] + [[package]] name = "nh3" version = "0.2.18" @@ -2099,24 +2135,6 @@ files = [ [package.dependencies] typing-extensions = ">=4.6.0,<4.7.0 || >4.7.0" -[[package]] -name = "pydash" -version = "8.0.3" -description = "The kitchen sink of Python utility libraries for doing \"stuff\" in a functional way. Based on the Lo-Dash Javascript library." -optional = false -python-versions = ">=3.8" -groups = ["dev"] -files = [ - {file = "pydash-8.0.3-py3-none-any.whl", hash = "sha256:c16871476822ee6b59b87e206dd27888240eff50a7b4cd72a4b80b43b6b994d7"}, - {file = "pydash-8.0.3.tar.gz", hash = "sha256:1b27cd3da05b72f0e5ff786c523afd82af796936462e631ffd1b228d91f8b9aa"}, -] - -[package.dependencies] -typing-extensions = ">3.10,<4.6.0 || >4.6.0" - -[package.extras] -dev = ["build", "coverage", "furo", "invoke", "mypy", "pytest", "pytest-cov", "pytest-mypy-testing", "ruff", "sphinx", "sphinx-autodoc-typehints", "tox", "twine", "wheel"] - [[package]] name = "pygments" version = "2.18.0" @@ -2821,25 +2839,25 @@ files = [ [[package]] name = "sphinx" -version = "6.2.1" +version = "7.3.7" description = "Python documentation generator" optional = false -python-versions = ">=3.8" +python-versions = ">=3.9" groups = ["dev"] files = [ - {file = "Sphinx-6.2.1.tar.gz", hash = "sha256:6d56a34697bb749ffa0152feafc4b19836c755d90a7c59b72bc7dfd371b9cc6b"}, - {file = "sphinx-6.2.1-py3-none-any.whl", hash = "sha256:97787ff1fa3256a3eef9eda523a63dbf299f7b47e053cfcf684a1c2a8380c912"}, + {file = "sphinx-7.3.7-py3-none-any.whl", hash = "sha256:413f75440be4cacf328f580b4274ada4565fb2187d696a84970c23f77b64d8c3"}, + {file = "sphinx-7.3.7.tar.gz", hash = "sha256:a4a7db75ed37531c05002d56ed6948d4c42f473a36f46e1382b0bd76ca9627bc"}, ] [package.dependencies] -alabaster = ">=0.7,<0.8" +alabaster = ">=0.7.14,<0.8.0" babel = ">=2.9" colorama = {version = ">=0.4.5", markers = "sys_platform == \"win32\""} -docutils = ">=0.18.1,<0.20" +docutils = ">=0.18.1,<0.22" imagesize = ">=1.3" Jinja2 = ">=3.0" packaging = ">=21.0" -Pygments = ">=2.13" +Pygments = ">=2.14" requests = ">=2.25.0" snowballstemmer = ">=2.0" sphinxcontrib-applehelp = "*" @@ -2847,23 +2865,24 @@ sphinxcontrib-devhelp = "*" sphinxcontrib-htmlhelp = ">=2.0.0" sphinxcontrib-jsmath = "*" sphinxcontrib-qthelp = "*" -sphinxcontrib-serializinghtml = ">=1.1.5" +sphinxcontrib-serializinghtml = ">=1.1.9" +tomli = {version = ">=2", markers = "python_version < \"3.11\""} [package.extras] docs = ["sphinxcontrib-websupport"] -lint = ["docutils-stubs", "flake8 (>=3.5.0)", "flake8-simplify", "isort", "mypy (>=0.990)", "ruff", "sphinx-lint", "types-requests"] -test = ["cython", "filelock", "html5lib", "pytest (>=4.6)"] +lint = ["flake8 (>=3.5.0)", "importlib_metadata", "mypy (==1.9.0)", "pytest (>=6.0)", "ruff (==0.3.7)", "sphinx-lint", "tomli", "types-docutils", "types-requests"] +test = ["cython (>=3.0)", "defusedxml (>=0.7.1)", "pytest (>=6.0)", "setuptools (>=67.0)"] [[package]] name = "sphinx-click" -version = "4.4.0" +version = "5.2.1" description = "Sphinx extension that automatically documents click applications" optional = false -python-versions = ">=3.7" +python-versions = ">=3.8" groups = ["dev"] files = [ - {file = "sphinx-click-4.4.0.tar.gz", hash = "sha256:cc67692bd28f482c7f01531c61b64e9d2f069bfcf3d24cbbb51d4a84a749fa48"}, - {file = "sphinx_click-4.4.0-py3-none-any.whl", hash = "sha256:2821c10a68fc9ee6ce7c92fad26540d8d8c8f45e6d7258f0e4fb7529ae8fab49"}, + {file = "sphinx_click-5.2.1-py3-none-any.whl", hash = "sha256:7aaa97bdce6fe315b3e719c085cd566e75470cbd91f1f6998b91213a09b8e7ec"}, + {file = "sphinx_click-5.2.1.tar.gz", hash = "sha256:a669773f76db05a3e04c163da91cd5e7db1a4761a6ea9eb074404a393094cde7"}, ] [package.dependencies] @@ -2871,6 +2890,30 @@ click = ">=7.0" docutils = "*" sphinx = ">=2.0" +[[package]] +name = "sphinx-starlight-builder" +version = "0.6.7" +description = "A Sphinx extension to add starlight mdx generation support." +optional = false +python-versions = ">=3.7" +groups = ["dev"] +files = [] +develop = false + +[package.dependencies] +docutils = "*" +sphinx = ">=5.1.0" +tabulate = "*" + +[package.extras] +dev = ["black", "bumpver", "coveralls", "flake8", "isort", "pip-tools", "pylint", "pytest", "pytest-cov", "sphinx (>=5.3.0)", "sphinxcontrib-plantuml", "sphinxcontrib.httpdomain"] + +[package.source] +type = "git" +url = "https://github.com/awesome-algorand/sphinx-starlight-builder" +reference = "HEAD" +resolved_reference = "5a156c2c000ee523427687f9cd0a0f23e08aee80" + [[package]] name = "sphinxcontrib-applehelp" version = "2.0.0" @@ -2972,23 +3015,19 @@ standalone = ["Sphinx (>=5)"] test = ["pytest"] [[package]] -name = "sphinxnotes-markdown-builder" -version = "0.5.7" -description = "sphinx builder that outputs markdown files, an active fork of clayrisser/sphinx-markdown-builder" +name = "tabulate" +version = "0.9.0" +description = "Pretty-print tabular data" optional = false -python-versions = "*" +python-versions = ">=3.7" groups = ["dev"] files = [ - {file = "sphinxnotes-markdown-builder-0.5.7.tar.gz", hash = "sha256:ad3e88fa1052d1a9bc4b75d7ae389ce51ffa896963bb19643e01b9120ca17ee9"}, - {file = "sphinxnotes_markdown_builder-0.5.7-py2.py3-none-any.whl", hash = "sha256:e1c49c31f72c36b29defc69fb05b7087b736355474b8806c814306ad3b42e2b8"}, + {file = "tabulate-0.9.0-py3-none-any.whl", hash = "sha256:024ca478df22e9340661486f85298cff5f6dcdba14f3813e8830015b9ed1948f"}, + {file = "tabulate-0.9.0.tar.gz", hash = "sha256:0095b12bf5966de529c0feb1fa08671671b3368eec77d7ef7ab114be2c068b3c"}, ] -[package.dependencies] -html2text = "*" -pydash = "*" -sphinx = "*" -unify = "*" -yapf = "*" +[package.extras] +widechars = ["wcwidth"] [[package]] name = "termcolor" @@ -3117,31 +3156,6 @@ typing-extensions = {version = ">=4.6.0", markers = "python_version < \"3.11\""} [package.extras] dev = ["mypy", "pylint", "pytest", "pytest-cov", "rich"] -[[package]] -name = "unify" -version = "0.5" -description = "Modifies strings to all use the same (single/double) quote where possible." -optional = false -python-versions = "*" -groups = ["dev"] -files = [ - {file = "unify-0.5.tar.gz", hash = "sha256:8ddce812b2457212b7598fe574c9e6eb3ad69710f445391338270c7f8a71723c"}, -] - -[package.dependencies] -untokenize = "*" - -[[package]] -name = "untokenize" -version = "0.1.1" -description = "Transforms tokens into original source code (while preserving whitespace)." -optional = false -python-versions = "*" -groups = ["dev"] -files = [ - {file = "untokenize-0.1.1.tar.gz", hash = "sha256:3865dbbbb8efb4bb5eaa72f1be7f3e0be00ea8b7f125c69cbd1f5fda926f37a2"}, -] - [[package]] name = "urllib3" version = "2.2.3" @@ -3220,23 +3234,6 @@ files = [ [package.extras] test = ["pytest (>=6.0.0)", "setuptools (>=65)"] -[[package]] -name = "yapf" -version = "0.40.2" -description = "A formatter for Python code" -optional = false -python-versions = ">=3.7" -groups = ["dev"] -files = [ - {file = "yapf-0.40.2-py3-none-any.whl", hash = "sha256:adc8b5dd02c0143108878c499284205adb258aad6db6634e5b869e7ee2bd548b"}, - {file = "yapf-0.40.2.tar.gz", hash = "sha256:4dab8a5ed7134e26d57c1647c7483afb3f136878b579062b786c9ba16b94637b"}, -] - -[package.dependencies] -importlib-metadata = ">=6.6.0" -platformdirs = ">=3.5.1" -tomli = ">=2.0.1" - [[package]] name = "zipp" version = "3.20.2" @@ -3261,4 +3258,4 @@ type = ["pytest-mypy"] [metadata] lock-version = "2.1" python-versions = ">=3.10,<3.14" -content-hash = "0cbccc11d932b237a9f2705e1151bbc9ff12080e39244beeb30b14fdc364da72" +content-hash = "f7489bfffdfa01fe4e38050d845effe0515a992076b2600f6080fe855b84a2e1" diff --git a/pyproject.toml b/pyproject.toml index 01acf9660..38ffba5e0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -41,13 +41,14 @@ pytest-httpx = "^0.21.2" python-semantic-release = "^7.32.2" pytest-cov = "^4.0.0" pre-commit = ">=2.20,<4.0" -sphinx = "^6.0.0" -sphinx-click = "^4.4.0" -sphinxnotes-markdown-builder = "^0.5.6" +sphinx = "^7.0.0" +sphinx-click = "^5.0.1" poethepoet = ">=0.17.1,<0.27.0" gfm-toc = "^0.0.7" pytest-xdist = "^3.4.0" pytest-sugar = "^1.0.0" +myst-parser = {version = "^4.0.1"} +sphinx-starlight-builder = {git = "https://github.com/awesome-algorand/sphinx-starlight-builder"} [build-system] requires = ["poetry-core"] @@ -57,10 +58,12 @@ build-backend = "poetry.core.masonry.api" algokit = "algokit.cli:algokit" [tool.poe.tasks] -docs_generate = "sphinx-build -b markdown -E docs/sphinx docs/cli" -docs_toc = "gfm-toc docs/cli/index.md -e 3" -docs_title = {shell = "(echo \"# AlgoKit CLI Reference Documentation\\n\\n\"; cat docs/cli/index.md) > docs/cli/temp.md && mv docs/cli/temp.md docs/cli/index.md"} -docs = ["docs_generate", "docs_toc", "docs_title"] +docs_starlight = "sphinx-build -M starlight docs .devportal" +docs_markdown = "sphinx-build -M markdown docs .devportal" +docs_reference = "sphinx-build -M markdown docs/cli docs/tmp" +docs_title = {shell = "(echo \"# AlgoKit CLI Reference Documentation\\n\\n\"; cat docs/tmp/markdown/index.md) > docs/tmp/temp.md && mv docs/tmp/temp.md docs/reference.md && rm -rf docs/tmp"} +docs = ["docs_reference", "docs_title", "docs_markdown", "docs_starlight"] +docs-reference = "sp" package_unix = "pyinstaller --clean --onedir --hidden-import jinja2_ansible_filters --hidden-import multiformats_config --copy-metadata algokit --name algokit --noconfirm src/algokit/__main__.py --add-data './misc/multiformats_config:multiformats_config/' --add-data './src/algokit/resources:algokit/resources/'" package_windows = { cmd = "scripts/package_windows.bat" } package_mac = { cmd = "scripts/package_mac.sh" }