Update documentation

ApeWorX · Feb 12, 2024 · 440de79 · 440de79
1 parent c0420d6
commit 440de79
Show file tree

Hide file tree

Showing 222 changed files with 35,979 additions and 160 deletions.
diff --git a/stable/.buildinfo b/stable/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: b353fec97cfa26793b44c7358f0e922a
+config: 6831f6818b24f880ce6c5e3aa0702b33
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/stable/.doctrees/commands/networks.doctree b/stable/.doctrees/commands/networks.doctree
diff --git a/stable/.doctrees/commands/plugins.doctree b/stable/.doctrees/commands/plugins.doctree
diff --git a/stable/.doctrees/environment.pickle b/stable/.doctrees/environment.pickle
diff --git a/stable/.doctrees/index.doctree b/stable/.doctrees/index.doctree
diff --git a/stable/.doctrees/methoddocs/ape.doctree b/stable/.doctrees/methoddocs/ape.doctree
diff --git a/stable/.doctrees/methoddocs/ape_accounts.doctree b/stable/.doctrees/methoddocs/ape_accounts.doctree
diff --git a/stable/.doctrees/methoddocs/api.doctree b/stable/.doctrees/methoddocs/api.doctree
diff --git a/stable/.doctrees/methoddocs/cli.doctree b/stable/.doctrees/methoddocs/cli.doctree
diff --git a/stable/.doctrees/methoddocs/contracts.doctree b/stable/.doctrees/methoddocs/contracts.doctree
diff --git a/stable/.doctrees/methoddocs/exceptions.doctree b/stable/.doctrees/methoddocs/exceptions.doctree
diff --git a/stable/.doctrees/methoddocs/managers.doctree b/stable/.doctrees/methoddocs/managers.doctree
diff --git a/stable/.doctrees/methoddocs/plugins.doctree b/stable/.doctrees/methoddocs/plugins.doctree
diff --git a/stable/.doctrees/methoddocs/types.doctree b/stable/.doctrees/methoddocs/types.doctree
diff --git a/stable/.doctrees/methoddocs/utils.doctree b/stable/.doctrees/methoddocs/utils.doctree
diff --git a/stable/.doctrees/userguides/contracts.doctree b/stable/.doctrees/userguides/contracts.doctree
diff --git a/stable/.doctrees/userguides/forking_networks.doctree b/stable/.doctrees/userguides/forking_networks.doctree
diff --git a/stable/.doctrees/userguides/installing_plugins.doctree b/stable/.doctrees/userguides/installing_plugins.doctree
diff --git a/stable/.doctrees/userguides/networks.doctree b/stable/.doctrees/userguides/networks.doctree
diff --git a/stable/.doctrees/userguides/quickstart.doctree b/stable/.doctrees/userguides/quickstart.doctree
diff --git a/stable/.doctrees/userguides/scripts.doctree b/stable/.doctrees/userguides/scripts.doctree
diff --git a/stable/_sources/index.md.txt b/stable/_sources/index.md.txt
@@ -14,6 +14,7 @@
    userguides/clis
    userguides/data
    userguides/networks
+   userguides/forking_networks
    userguides/developing_plugins
    userguides/config
    userguides/transactions

diff --git a/stable/_sources/methoddocs/cli.md.txt b/stable/_sources/methoddocs/cli.md.txt
@@ -43,11 +43,3 @@ scripts.
     :members:
     :show-inheritance:
 ```
-
-## Utilities
-
-```{eval-rst}
-.. automodule:: ape.cli.utils
-    :members:
-    :show-inheritance:
-```
diff --git a/stable/_sources/userguides/contracts.md.txt b/stable/_sources/userguides/contracts.md.txt
@@ -59,7 +59,7 @@ To avoid naming collisions with other properties on the `project` object, you ca
 ```python
 from ape import project
 
-contract = property.get_contract("MyContract")  # Same as `project.MyContract`.
+contract = project.get_contract("MyContract")  # Same as `project.MyContract`.
 ```
 
 Notice when deploying, we have to specify the `sender=` kwarg because `deploy` operations are transactions.

diff --git a/stable/_sources/userguides/forking_networks.md.txt b/stable/_sources/userguides/forking_networks.md.txt
@@ -0,0 +1,81 @@
+# Forking Networks
+
+You can fork live networks in Ape.
+To do so, ensure you are using a provider plugin with forking features.
+Some options are:
+
+1. [ApeWorX/ape-foundry](https://github.com/ApeWorX/ape-foundry)
+2. [ApeWorX/ape-hardhat](https://github.com/ApeWorX/ape-hardhat)
+
+You can install one of these plugins by doing:
+
+```shell
+ape plugins install <foundry|hardhat>
+```
+
+Ensure you have also configured your upstream network (the network you are forking).
+For example, if forking `ethereum:mainnet` and using `alchemy`, set `alchemy` as the default mainnet provider:
+
+```yaml
+ethereum:
+  mainnet:
+    default_provider: alchemy
+```
+
+Now, you can start and connect to your forked-network:
+
+```yaml
+ape console --network ethereum:mainnet-fork:foundry
+```
+
+Learn more about setting up networks in the [the networks guide](./networks.html).
+
+## Forking Plugin Networks
+
+You can also fork L2 plugin networks.
+For example, to fork a network such as Optimism, install the `ape-optimism` plugin:
+
+```shell
+ape plugins install optimism
+```
+
+Then, just like you did for `ethereum`, configure `optimism`'s default mainnet provider:
+
+```yaml
+optimism:
+  mainnet:
+    default_provider: alchemy
+```
+
+Now, you can start and connect to your forked-network:
+
+```yaml
+ape console --network optimism:mainnet-fork:foundry
+```
+
+## Configure Default
+
+If you want to change the default network from `local` to your forked network, add the following config:
+
+```yaml
+<ecosystem-name>:
+  default_network: <network-name>_fork
+```
+
+Where `ecosystem-name` is the ecosystem containing the network and `network-name` is the network you are forking.
+
+## Forked Context
+
+If you are already connected to a live network wish to temporarily fork it, use the [fork() context manager](../methoddocs/managers.html#ape.managers.networks.NetworkManager.fork):
+
+```python
+from ape import networks
+
+def main():
+    with networks.ethereum.mainnet.use_provider("alchemy") as alchemy:
+        print(alchemy.name)
+        with networks.fork(provider_name="foundry") as foundry:
+            print(foundry.name)
+```
+
+Learn more about the fork context manager [here](./networks.html#forked-context).
diff --git a/stable/_sources/userguides/installing_plugins.md.txt b/stable/_sources/userguides/installing_plugins.md.txt
@@ -64,6 +64,25 @@ Or from the CLI like:
 ape plugins install "foobar@git+https://github.com/<owner-of-plugin>/ape-foobar.git@<branch/name>"
 ```
 
+## Plugin Versions
+
+By default, `ape plugins` commands install plugins within your current Ape version specification.
+For example, if you have Ape 0.6.5 installed and you install `ape-tokens` without specifying a version, it defaults to `ape-tokens>=0.6.0,<0.7` so it is compatible does not change your Ape version.
+To upgrade plugins to a new minor version, you have to first update Ape.
+
+We provide an easy way to update your entire Ape ecosystem using the command:
+
+```shell
+ape plugins update
+```
+
+Now, both Ape and all the plugins will maximally update.
+Alternatively, you use the `change-version` command to install a specific version of everything at once:
+
+```shell
+ape plugins change-version 0.6.0
+```
+
 ## Plugin Types
 
 There are many types of plugins available, including compilers, providers, networks, and CLI-based plugins.

diff --git a/stable/_sources/userguides/networks.md.txt b/stable/_sources/userguides/networks.md.txt
@@ -222,6 +222,22 @@ ethereum:
 
 For a full list of network configurations like this (for both custom and plugin-based networks), [see this section](#configuring-networks).
 
+**NOTE**: This also works if configuring a custom ecosystem.
+If using a custom ecosystem, use the custom ecosystem name as the top-level config key instead:
+
+```yaml
+networks:
+  custom:
+    - name: mainnet
+      ecosystem: shibarium
+      base_ecosystem_plugin: polygon  # Closest base class.
+      chain_id: 109  # This must be correct or txns will fail.
+
+shibarium:
+  mainnet:
+    default_transaction_type: 0  # Use static-fee transactions for Shibarium.
+```
+
 ### Custom Networks by CLI
 
 Ape also lets you connect to custom networks on-the-fly!
@@ -478,9 +494,11 @@ We can switch to a forked network by doing this:
 from ape import networks
 
 def main():
-    with networks.fork("foundry"):
+    with networks.fork(provider_name="foundry"):
         ...
         # Do stuff on a local, forked version of mainnet
 
     # Switch back to mainnet.
 ```
+
+Learn more about forking networks in the [forked-networks guide](./forking_networks.html).
diff --git a/stable/_sources/userguides/scripts.md.txt b/stable/_sources/userguides/scripts.md.txt
@@ -42,7 +42,7 @@ from ape.cli import ConnectedProviderCommand
 
 @click.command(cls=ConnectedProviderCommand)
 def cli(ecosystem, network):
-    click(f"You selected a provider on ecosystem '{ecosystem.name}' and {network.name}.")
+    click.echo(f"You selected a provider on ecosystem '{ecosystem.name}' and {network.name}.")
 
 @click.command(cls=ConnectedProviderCommand)
 def cli(network, provider):

diff --git a/stable/commands/accounts.html b/stable/commands/accounts.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.7">v0.7.7</option>
                 <option value="v0.7.6">v0.7.6</option>
                 <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
@@ -143,6 +144,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../userguides/clis.html">CLIs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/data.html">Querying Data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/networks.html">Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../userguides/forking_networks.html">Forking Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/developing_plugins.html">Developing Plugins</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/config.html">Configure Ape</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/transactions.html">Making Transactions</a></li>

diff --git a/stable/commands/compile.html b/stable/commands/compile.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.7">v0.7.7</option>
                 <option value="v0.7.6">v0.7.6</option>
                 <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
@@ -143,6 +144,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../userguides/clis.html">CLIs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/data.html">Querying Data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/networks.html">Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../userguides/forking_networks.html">Forking Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/developing_plugins.html">Developing Plugins</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/config.html">Configure Ape</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/transactions.html">Making Transactions</a></li>

diff --git a/stable/commands/console.html b/stable/commands/console.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.7">v0.7.7</option>
                 <option value="v0.7.6">v0.7.6</option>
                 <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
@@ -143,6 +144,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../userguides/clis.html">CLIs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/data.html">Querying Data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/networks.html">Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../userguides/forking_networks.html">Forking Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/developing_plugins.html">Developing Plugins</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/config.html">Configure Ape</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/transactions.html">Making Transactions</a></li>

diff --git a/stable/commands/init.html b/stable/commands/init.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.7">v0.7.7</option>
                 <option value="v0.7.6">v0.7.6</option>
                 <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
@@ -143,6 +144,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../userguides/clis.html">CLIs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/data.html">Querying Data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/networks.html">Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../userguides/forking_networks.html">Forking Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/developing_plugins.html">Developing Plugins</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/config.html">Configure Ape</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/transactions.html">Making Transactions</a></li>

diff --git a/stable/commands/networks.html b/stable/commands/networks.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.7">v0.7.7</option>
                 <option value="v0.7.6">v0.7.6</option>
                 <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
@@ -143,6 +144,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../userguides/clis.html">CLIs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/data.html">Querying Data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/networks.html">Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../userguides/forking_networks.html">Forking Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/developing_plugins.html">Developing Plugins</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/config.html">Configure Ape</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/transactions.html">Making Transactions</a></li>
@@ -254,7 +256,7 @@ <h2>list<a class="headerlink" href="#networks-list" title="Permalink to this hea
 <dd><p>Filter the results by network</p>
 <dl class="field-list simple">
 <dt class="field-odd">Options<span class="colon">:</span></dt>
-<dd class="field-odd"><p>sepolia-fork | goerli | local | mainnet | sepolia | goerli-fork | mainnet-fork</p>
+<dd class="field-odd"><p>sepolia-fork | local | mainnet | goerli | sepolia | goerli-fork | mainnet-fork</p>
 </dd>
 </dl>
 </dd></dl>
@@ -291,7 +293,7 @@ <h2>run<a class="headerlink" href="#networks-run" title="Permalink to this headi
 <dd><p>Override the default network and provider. (see <cite>ape networks list</cite> for options)</p>
 <dl class="field-list simple">
 <dt class="field-odd">Options<span class="colon">:</span></dt>
-<dd class="field-odd"><p>:mainnet:geth | ethereum:mainnet:geth | :mainnet | ethereum:mainnet | :goerli:geth | ethereum:goerli:geth | :goerli | ethereum:goerli | :sepolia:geth | ethereum:sepolia:geth | :sepolia | ethereum:sepolia | ::geth | :local:geth | ethereum::geth | ethereum:local:geth | ::test | :local:test | ethereum::test | ethereum:local:test | :local | ethereum:local | ethereum</p>
+<dd class="field-odd"><p>:mainnet:geth | ethereum:mainnet:geth | :mainnet | ethereum:mainnet | :goerli:geth | ethereum:goerli:geth | :goerli | ethereum:goerli | :sepolia:geth | ethereum:sepolia:geth | :sepolia | ethereum:sepolia | ::test | :local:test | ethereum::test | ethereum:local:test | ::geth | :local:geth | ethereum::geth | ethereum:local:geth | :local | ethereum:local | ethereum</p>
 </dd>
 </dl>
 </dd></dl>

diff --git a/stable/commands/plugins.html b/stable/commands/plugins.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.7">v0.7.7</option>
                 <option value="v0.7.6">v0.7.6</option>
                 <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
@@ -143,6 +144,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../userguides/clis.html">CLIs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/data.html">Querying Data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/networks.html">Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../userguides/forking_networks.html">Forking Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/developing_plugins.html">Developing Plugins</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/config.html">Configure Ape</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/transactions.html">Making Transactions</a></li>
@@ -163,9 +165,11 @@
 <li class="toctree-l1"><a class="reference internal" href="init.html">init</a></li>
 <li class="toctree-l1"><a class="reference internal" href="networks.html">networks</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">plugins</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#plugins-change-version">change-version</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#plugins-install">install</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#plugins-list">list</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#plugins-uninstall">uninstall</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#plugins-update">update</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="run.html">run</a></li>
@@ -215,6 +219,20 @@ <h1>plugins<a class="headerlink" href="#plugins" title="Permalink to this headin
 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>plugins<span class="w"> </span><span class="o">[</span>OPTIONS<span class="o">]</span><span class="w"> </span>COMMAND<span class="w"> </span><span class="o">[</span>ARGS<span class="o">]</span>...
 </pre></div>
 </div>
+<section id="plugins-change-version">
+<h2>change-version<a class="headerlink" href="#plugins-change-version" title="Permalink to this heading"></a></h2>
+<p>Change ape and all plugins version</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>plugins<span class="w"> </span>change-version<span class="w"> </span><span class="o">[</span>OPTIONS<span class="o">]</span><span class="w"> </span>VERSION
+</pre></div>
+</div>
+<p class="rubric">Arguments</p>
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-plugins-change-version-arg-VERSION">
+<span id="cmdoption-plugins-change-version-arg-version"></span><span class="sig-name descname"><span class="pre">VERSION</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-plugins-change-version-arg-VERSION" title="Permalink to this definition"></a></dt>
+<dd><p>Required argument</p>
+</dd></dl>
+
+</section>
 <section id="plugins-install">
 <h2>install<a class="headerlink" href="#plugins-install" title="Permalink to this heading"></a></h2>
 <p>Install plugins</p>
@@ -294,6 +312,13 @@ <h2>uninstall<a class="headerlink" href="#plugins-uninstall" title="Permalink to
 <dd><p>Optional argument(s)</p>
 </dd></dl>
 
+</section>
+<section id="plugins-update">
+<h2>update<a class="headerlink" href="#plugins-update" title="Permalink to this heading"></a></h2>
+<p>Update Ape and all plugins to the next version</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>plugins<span class="w"> </span>update<span class="w"> </span><span class="o">[</span>OPTIONS<span class="o">]</span>
+</pre></div>
+</div>
 </section>
 </section>
 

diff --git a/stable/commands/pm.html b/stable/commands/pm.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.7">v0.7.7</option>
                 <option value="v0.7.6">v0.7.6</option>
                 <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
@@ -143,6 +144,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../userguides/clis.html">CLIs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/data.html">Querying Data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/networks.html">Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../userguides/forking_networks.html">Forking Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/developing_plugins.html">Developing Plugins</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/config.html">Configure Ape</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/transactions.html">Making Transactions</a></li>

diff --git a/stable/commands/run.html b/stable/commands/run.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.7">v0.7.7</option>
                 <option value="v0.7.6">v0.7.6</option>
                 <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
@@ -143,6 +144,7 @@
 <li class="toctree-l1"><a class="reference internal" href="../userguides/clis.html">CLIs</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/data.html">Querying Data</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/networks.html">Networks</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../userguides/forking_networks.html">Forking Networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/developing_plugins.html">Developing Plugins</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/config.html">Configure Ape</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../userguides/transactions.html">Making Transactions</a></li>