docs: myst markdown

.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

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
 

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**

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
 

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
 

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"
+# }

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.

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.

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.

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).

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 <https://mainnet-api.algonode.cloud> [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.

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.

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).

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).

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`.

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