docs: wording tweaks to the compile docs

docs/cli/index.md

@@ -289,7 +289,7 @@ algokit bootstrap poetry [OPTIONS]
 
 ## compile
 
-Compile smart contracts written in a high level language to TEAL.
+Compile smart contracts written in a high-level language to TEAL.
 
 ```shell
 algokit compile [OPTIONS] COMMAND [ARGS]...
@@ -299,11 +299,11 @@ algokit compile [OPTIONS] COMMAND [ARGS]...
 
 
 ### -v, --version <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.
+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
 
-Compile Python contract(s) to TEAL using the PuyaPy compiler.
+Compile Algorand Python contract(s) to TEAL using the PuyaPy compiler.
 
 ```shell
 algokit compile py [OPTIONS] [PUYAPY_ARGS]...
@@ -317,7 +317,7 @@ Optional argument(s)
 
 ### python
 
-Compile Python contract(s) to TEAL using the PuyaPy compiler.
+Compile Algorand Python contract(s) to TEAL using the PuyaPy compiler.
 
 ```shell
 algokit compile python [OPTIONS] [PUYAPY_ARGS]...

docs/features/compile.md

@@ -1,20 +1,22 @@
 # AlgoKit Compile
 
-The AlgoKit Compile feature enables you to compile smart contract applications written in a supported high level language to TEAL.
+The AlgoKit Compile feature enables you to compile smart contracts (apps) and smart signatures (logic signatures) written in a supported high-level language to TEAL, for deployment on the Algorand Virtual Machine (AVM).
 
-When running the compile command, AlgoKit will take care of working out which compiler you need and dynamically resolve it. Additionally AlgoKit will detect if an appropriate compiler version is already installed globally on your machine or is included in your project and utilise that.
+When running the compile command, AlgoKit will take care of working out which compiler you need and dynamically resolve it. Additionally, AlgoKit will detect if an appropriate compiler version is already installed globally on your machine or is included in your project and utilize that.
 
 ## Prerequisites
 
 This command dynamically loads the appropriate compiler using [pipx](https://pipx.pypa.io/stable/). As such pipx is required when using this command.
 
-## What is Puya and PuyaPy?
+## What is Algorand Python & PuyaPy?
 
-Puya is a multi-stage optimizing TEAL compiler, that allows developers to write Python smart contracts using the PuyaPy syntax.
+Algorand Python is a semantically and syntactically compatible, typed Python language that works with standard Python tooling and allows you to express smart contracts (apps) and smart signatures (logic signatures) for deployment on the Algorand Virtual Machine (AVM).
 
-If you want to know more, take a peek at the [Puya docs](https://github.com/algorandfoundation/puya/blob/main/docs/index.md).
+This is done by compiling Algorand Python using the PuyaPy compiler, which takes Algorand Python and outputs valid, optimised TEAL code with execution semantics that match the given Python code.
 
-The below example is a valid PuyaPy Python smart contract.
+If you want to know more, check out the [PuyaPy docs](https://github.com/algorandfoundation/puya/blob/main/docs/index.md).
+
+The below example is a valid Algorand Python smart contract.
 
 ```py
 from puyapy import ARC4Contract, arc4
@@ -25,21 +27,21 @@ class HelloWorldContract(ARC4Contract):
         return "Hello, " + name
 ```
 
-For more complex example, check out the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) directory in the [Puya repo](https://github.com/algorandfoundation/puya).
+For more complex examples, check out the [examples](https://github.com/algorandfoundation/puya/tree/main/examples) in the [PuyaPy repo](https://github.com/algorandfoundation/puya).
 
 ## Usage
 
-Available commands and possible usage is as follows:
+Available commands and possible usage are as follows:
 
 ```
 Usage: algokit compile [OPTIONS] COMMAND [ARGS]...
 
-  Compile smart contracts written in a high level language to TEAL.
+  Compile smart contracts written in a high-level language to TEAL.
 
 Options:
   -v, --version TEXT  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
+                      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.
   -h, --help          Show this message and exit.
 
@@ -50,7 +52,7 @@ Commands:
 
 ### Compile Python
 
-The command `algokit compile python` or `algokit compile py` will run the [PuyaPy](https://github.com/algorandfoundation/puya) compiler against the supplied PuyaPy compatible Python smart contract.
+The command `algokit compile python` or `algokit compile py` will run the [PuyaPy](https://github.com/algorandfoundation/puya) compiler against the supplied Algorand Python smart contract.
 
 All arguments supplied to the command are passed directly to PuyaPy and as such this command supports all options of the specific PuyaPy compiler version being used.
 
@@ -70,19 +72,19 @@ To check which version of the PuyaPy compiler is being used, run the following:
 algokit compile python --version
 ```
 
-To compile a single PuyaPy Python smart contract and write the output to a specific location, run the following:
+To compile a single Algorand Python smart contract and write the output to a specific location, run the following:
 
 ```shell
 algokit compile python hello_world/contract.py --out-dir hello_world/out
 ```
 
-To compile multiple PuyaPy Python smart contracts and write the output to a specific location, run the following:
+To compile multiple Algorand Python smart contracts and write the output to a specific location, run the following:
 
 ```shell
 algokit compile python hello_world/contract.py calculator/contract.py --out-dir my_contracts
 ```
 
-To compile a directory of PuyaPy Python smart contracts and write the output to the default location, run the following:
+To compile a directory of Algorand Python smart contracts and write the output to the default location, run the following:
 
 ```shell
 algokit compile python my_contracts

src/algokit/cli/compile.py

@@ -7,7 +7,7 @@
 logger = logging.getLogger(__name__)
 
 
-@click.group("compile", short_help="Compile smart contracts written in a high level language to TEAL.")
+@click.group("compile", short_help="Compile smart contracts written in a high-level language to TEAL.")
 @click.option(
     "-v",
     "--version",
@@ -17,14 +17,14 @@
     help=(
         "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 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."
     ),
 )
 @click.pass_context
 def compile_group(context: click.Context, version: str | None) -> None:
-    """Compile smart contracts written in a high level language to TEAL."""
+    """Compile smart contracts written in a high-level language to TEAL."""
     context.ensure_object(dict)
     context.obj["version"] = version
 

src/algokit/cli/compilers/python.py

@@ -27,7 +27,7 @@ def invoke_puyapy(context: click.Context, puyapy_args: list[str]) -> None:
     if run_result.exit_code != 0:
         click.secho(
             "An error occurred during compile. Please ensure that any supplied arguments are valid "
-            "and any files passed are valid PuyaPy code before retrying.",
+            "and any files passed are valid Algorand Python code before retrying.",
             err=True,
             fg="red",
         )
@@ -42,7 +42,7 @@ def common_puyapy_command_options(function: _AnyCallable) -> click.Command:
             "ignore_unknown_options": True,
         },
         add_help_option=False,
-        help="Compile Python contract(s) to TEAL using the PuyaPy compiler.",
+        help="Compile Algorand Python contract(s) to TEAL using the PuyaPy compiler.",
     )(function)