docs: regen docs

docs/html/_sources/capabilities/debugging.md.txt

@@ -0,0 +1,30 @@
+# Debugger
+
+The AlgoKit Python Utilities package provides a set of debugging tools that can be used to simulate and trace transactions on the Algorand blockchain. These tools and methods are optimized for developers who are building applications on Algorand and need to test and debug their smart contracts via [AVM Debugger extension](link to vscode extension).
+
+## Configuration
+
+The `config.py` file contains the `UpdatableConfig` class which manages and updates configuration settings for the AlgoKit project. The class has the following attributes:
+
+-   `debug`: Indicates whether debug mode is enabled.
+-   `project_root`: The path to the project root directory. Can be ignored if you are using `algokit_utils` inside an `algokit` compliant project (containing `.algokit.toml` file). For non algokit compliant projects, simply provide the path to the folder where you want to store sourcemaps and traces to be used with [`AVM Debugger`](links to extension). Alternatively you can also set the value via the `ALGOKIT_PROJECT_ROOT` environment variable.
+-   `trace_all`: Indicates whether to trace all operations. Defaults to false, this means that when debug mode is enabled, any (or all) application client calls performed via `algokit_utils` will store responses from `simulate` endpoint. These files are called traces, and can be used with [AVM Debugger](link to vscode extension) to debug TEAL source codes, transactions in the atomic group and etc.
+-   `trace_buffer_size_mb`: The size of the trace buffer in megabytes. By default uses 256 megabytes. When output folder containing debug trace files exceedes the size, oldest files are removed to optimize for storage consumption.
+-   `max_search_depth`: The maximum depth to search for a an `algokit` config file. By default it will traverse at most 10 folders searching for `.algokit.toml` file which will be used to assume algokit compliant project root path.
+
+The `configure` method can be used to set these attributes.
+
+To enable debug mode in your project you can configure it as follows:
+
+```py
+from algokit_utils.config import config
+
+config.configure(debug=True)
+```
+
+## Debugging Utilities
+
+Debugging utilities can be used to simplify gathering artifacts to be used with [AlgoKit AVM Debugger](https://github.com/algorandfoundation/algokit-avm-vscode-debugger) in non algokit compliant projects. The following methods are provided:
+
+-   `persist_sourcemaps`: This method persists the sourcemaps for the given sources as AVM Debugger compliant artifacts. It takes a list of `PersistSourceMapInput` objects, a `Path` object representing the root directory of the project, an `AlgodClient` object for interacting with the Algorand blockchain, and a boolean indicating whether to dump teal source files along with sourcemaps.
+-   `simulate_and_persist_response`: This method simulates the atomic transactions using the provided `AtomicTransactionComposer` object and `AlgodClient` object, and persists the simulation response to an AVM Debugger compliant JSON file. It takes an `AtomicTransactionComposer` object representing the atomic transactions to be simulated and persisted, a `Path` object representing the root directory of the project, an `AlgodClient` object representing the Algorand client, and a float representing the size of the trace buffer in megabytes.

docs/html/apidocs/algokit_utils/algokit_utils.html

@@ -385,20 +385,20 @@ <h3>Functions<a class="headerlink" href="#functions" title="Permalink to this he
 The <code class="docutils literal notranslate"><span class="pre">optOut</span></code> function manages the opt-out process, permitting the account to discontinue holding a group of assets.</p></td>
 </tr>
 <tr class="row-even"><td><p><a class="reference internal" href="#algokit_utils.persist_sourcemaps" title="algokit_utils._debugging.persist_sourcemaps"><code class="xref py py-obj docutils literal notranslate"><span class="pre">persist_sourcemaps</span></code></a></p></td>
-<td><p>Persist the sourcemaps for the given sources as AVM Debugger compliant artifacts.
+<td><p>Persist the sourcemaps for the given sources as an AlgoKit AVM Debugger compliant artifacts.
 Args:
 sources (list[PersistSourceMapInput]): A list of PersistSourceMapInput objects.
 project_root (Path): The root directory of the project.
 client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain.
 with_sources (bool): If True, it will dump teal source files along with sourcemaps.
-Default is True, as needed by AVM debugger.</p></td>
+Default is True, as needed by an AlgoKit AVM debugger.</p></td>
 </tr>
 <tr class="row-odd"><td><p><a class="reference internal" href="#algokit_utils.replace_template_variables" title="algokit_utils.deploy.replace_template_variables"><code class="xref py py-obj docutils literal notranslate"><span class="pre">replace_template_variables</span></code></a></p></td>
 <td><p>Replaces <code class="docutils literal notranslate"><span class="pre">TMPL_*</span></code> variables in <code class="docutils literal notranslate"><span class="pre">program</span></code> with <code class="docutils literal notranslate"><span class="pre">template_values</span></code></p></td>
 </tr>
 <tr class="row-even"><td><p><a class="reference internal" href="#algokit_utils.simulate_and_persist_response" title="algokit_utils._debugging.simulate_and_persist_response"><code class="xref py py-obj docutils literal notranslate"><span class="pre">simulate_and_persist_response</span></code></a></p></td>
 <td><p>Simulates the atomic transactions using the provided <code class="docutils literal notranslate"><span class="pre">AtomicTransactionComposer</span></code> object and <code class="docutils literal notranslate"><span class="pre">AlgodClient</span></code> object,
-and persists the simulation response to an AVM Debugger compliant JSON file.</p></td>
+and persists the simulation response to an AlgoKit AVM Debugger compliant JSON file.</p></td>
 </tr>
 <tr class="row-odd"><td><p><a class="reference internal" href="#algokit_utils.transfer" title="algokit_utils._transfer.transfer"><code class="xref py py-obj docutils literal notranslate"><span class="pre">transfer</span></code></a></p></td>
 <td><p>Transfer µALGOs between accounts</p></td>
@@ -1703,13 +1703,13 @@ <h4>Example<a class="headerlink" href="#example" title="Permalink to this headin
 <dl class="py function">
 <dt class="sig sig-object py" id="algokit_utils.persist_sourcemaps">
 <span class="sig-prename descclassname"><span class="pre">algokit_utils.</span></span><span class="sig-name descname"><span class="pre">persist_sourcemaps</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sources</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.12)"><span class="pre">list</span></a><span class="p"><span class="pre">[</span></span><span class="pre">algokit_utils._debugging.PersistSourceMapInput</span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">project_root</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path" title="(in Python v3.12)"><span class="pre">pathlib.Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">client</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://py-algorand-sdk.readthedocs.io/en/latest/algosdk/v2client/algod.html#algosdk.v2client.algod.AlgodClient" title="(in algosdk)"><span class="pre">algosdk.v2client.algod.AlgodClient</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">with_sources</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.12)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.12)"><span class="pre">None</span></a></span></span><a class="headerlink" href="#algokit_utils.persist_sourcemaps" title="Permalink to this definition"></a></dt>
-<dd><p>Persist the sourcemaps for the given sources as AVM Debugger compliant artifacts.
+<dd><p>Persist the sourcemaps for the given sources as an AlgoKit AVM Debugger compliant artifacts.
 Args:
 sources (list[PersistSourceMapInput]): A list of PersistSourceMapInput objects.
 project_root (Path): The root directory of the project.
 client (AlgodClient): An AlgodClient object for interacting with the Algorand blockchain.
 with_sources (bool): If True, it will dump teal source files along with sourcemaps.
-Default is True, as needed by AVM debugger.</p>
+Default is True, as needed by an AlgoKit AVM debugger.</p>
 </dd></dl>
 
 <dl class="py function">
@@ -1726,7 +1726,7 @@ <h4>Example<a class="headerlink" href="#example" title="Permalink to this headin
 <dt class="sig sig-object py" id="algokit_utils.simulate_and_persist_response">
 <span class="sig-prename descclassname"><span class="pre">algokit_utils.</span></span><span class="sig-name descname"><span class="pre">simulate_and_persist_response</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">atc</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://py-algorand-sdk.readthedocs.io/en/latest/algosdk/atomic_transaction_composer.html#algosdk.atomic_transaction_composer.AtomicTransactionComposer" title="(in algosdk)"><span class="pre">algosdk.atomic_transaction_composer.AtomicTransactionComposer</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">project_root</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/pathlib.html#pathlib.Path" title="(in Python v3.12)"><span class="pre">pathlib.Path</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">algod_client</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://py-algorand-sdk.readthedocs.io/en/latest/algosdk/v2client/algod.html#algosdk.v2client.algod.AlgodClient" title="(in algosdk)"><span class="pre">algosdk.v2client.algod.AlgodClient</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffer_size_mb</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.12)"><span class="pre">float</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">256</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://py-algorand-sdk.readthedocs.io/en/latest/algosdk/atomic_transaction_composer.html#algosdk.atomic_transaction_composer.SimulateAtomicTransactionResponse" title="(in algosdk)"><span class="pre">algosdk.atomic_transaction_composer.SimulateAtomicTransactionResponse</span></a></span></span><a class="headerlink" href="#algokit_utils.simulate_and_persist_response" title="Permalink to this definition"></a></dt>
 <dd><p>Simulates the atomic transactions using the provided <code class="docutils literal notranslate"><span class="pre">AtomicTransactionComposer</span></code> object and <code class="docutils literal notranslate"><span class="pre">AlgodClient</span></code> object,
-and persists the simulation response to an AVM Debugger compliant JSON file.</p>
+and persists the simulation response to an AlgoKit AVM Debugger compliant JSON file.</p>
 <dl class="myst field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
 <dd class="field-odd"><ul class="simple">
@@ -1742,7 +1742,8 @@ <h4>Example<a class="headerlink" href="#example" title="Permalink to this headin
 </dd>
 </dl>
 <p>Returns:
-SimulateAtomicTransactionResponse: The simulated response after persisting it for AVM Debugger consumption.</p>
+SimulateAtomicTransactionResponse: The simulated response after persisting it
+for AlgoKit AVM Debugger consumption.</p>
 </dd></dl>
 
 <dl class="py function">