docs: update userguides and notes [APE-1752] (#2109)

CONTRIBUTING.md

@@ -15,7 +15,9 @@ source venv/bin/activate
 pip install -e .'[dev]'
 ```
 
-**NOTE**: You might run into issues where you have a local install and are trying to work with a plugin pinned to a specific version.
+```{note}
+You might run into issues where you have a local install and are trying to work with a plugin pinned to a specific version.
+```
 
 [The easiest solution](https://github.com/ApeWorX/ape/issues/90) to this is to fetch the tags via `git fetch upstream --tags` and reinstall via `pip install .`.
 You will then have the correct version.
@@ -66,7 +68,10 @@ python -m http.server --directory "docs/_build/" --bind 127.0.0.1 1337
 ```
 
 Then, open your browser to `127.0.0.1:1337` and click the `ape` directory link.
-NOTE: Serving from `"docs/_build/"` rather than `"docs/_build/ape"` is necessary to make routing work.
+
+```{note}
+Serving from `"docs/_build/"` rather than `"docs/_build/ape"` is necessary to make routing work.
+```
 
 ## Pull Requests
 

README.md

@@ -95,8 +95,10 @@ Ape's modular plugin system allows users to have an interoperable experience wit
 
 - Learn more about **developing** your own plugins from this [developing user guide](https://docs.apeworx.io/ape/stable/userguides/developing_plugins.html).
 
-**NOTE**: If a plugin does not originate from the [ApeWorX GitHub Organization](https://github.com/ApeWorX?q=ape&type=all), you will get a warning about installing 3rd-party plugins.
+```{note}
+If a plugin does not originate from the [ApeWorX GitHub Organization](https://github.com/ApeWorX?q=ape&type=all), you will get a warning about installing 3rd-party plugins.
 Install 3rd party plugins at your own risk.
+```
 
 [accounts-guide]: https://docs.apeworx.io/ape/stable/userguides/accounts.html
 [actions-badge]: https://github.com/ApeWorX/ape/actions/workflows/test.yaml/badge.svg

docs/conf.py

@@ -83,8 +83,9 @@
 # Set some default to avoid unnecessary repetitious directives.
 autodoc_default_options = {
     "exclude-members": (
-        "__repr__, __weakref__, __metaclass__, __init__, "
-        "model_config, model_fields, model_post_init, model_computed_fields"
+        "__repr__, __weakref__, __metaclass__, __init__, __format__,  __new__, __str__, __dir__"
+        "model_config, model_fields, model_post_init, model_computed_fields,"
+        "__ape_extra_attributes__,"
     )
 }
 

docs/userguides/accounts.md

@@ -30,12 +30,12 @@ def test_my_contract_method(accounts):
 To access the same prefunded accounts in your scripts or console, use the root `accounts` object and the [test_accounts](../methoddocs/managers.html#ape.managers.accounts.AccountManager.test_accounts) property:
 
 ```{eval-rst}
-
 .. doctest::
 
->>> from ape import accounts
+  >>> from ape import accounts
+
+  >>> sender = accounts.test_accounts[0]
 
->>> sender = accounts.test_accounts[0]
 ```
 
 You can configure your test accounts using your `ape-config.yaml` file:
@@ -46,23 +46,27 @@ test:
   number_of_accounts: 5
 ```
 
-**WARN**: NEVER put a seed phrase with real funds here.
+```{warning}
+NEVER put a seed phrase with real funds here.
+```
+
 The accounts generated from this seed are solely for testing and debugging purposes.
 
 ### Creating new test accounts
 
 You can create a new test account by doing the following:
 
 ```{eval-rst}
-
 .. doctest::
 
->>> from ape import accounts
+  >>> from ape import accounts
 
->>> account = accounts.test_accounts.generate_test_account()
+  >>> account = accounts.test_accounts.generate_test_account()
 ```
 
-**NOTE**: Creating a new test account means it will be unfunded by default.
+```{note}
+Creating a new test account means it will be unfunded by default.
+```
 
 Learn more about test accounts from the [testing guide](./testing.html#accounts-fixture).
 
@@ -264,7 +268,10 @@ message = encode_defunct(text="Hello Apes!")
 signature = account.sign_message(message)
 ```
 
-**NOTE**: Ape's `sign_message` API intentionally accepts `Any` as the message argument type.
+```{note}
+Ape's `sign_message` API intentionally accepts `Any` as the message argument type.
+```
+
 Account plugins decide what data-types to support.
 Most Ethereum account plugins, such as `ape-account`, are able to sign messages like the example above.
 However, you can also provide other types, such as a `str` directly:
@@ -351,7 +358,9 @@ message = encode_defunct(text="Hello Apes!")
 signature = account.sign_message(message)
 ```
 
-**NOTE**: Alternatively, you may use the `passphrase=` kwarg on methods `account.set_autosign()` and `account.unlock()`, but we highly recommend using the environment variable approach to avoid accidentally leaking your passphrase.
+```{note}
+Alternatively, you may use the `passphrase=` kwarg on methods `account.set_autosign()` and `account.unlock()`, but we highly recommend using the environment variable approach to avoid accidentally leaking your passphrase.
+```
 
 ## Hardware Wallets
 

docs/userguides/clis.md

@@ -150,12 +150,12 @@ And when invoking the command from the CLI, it would look like the following:
 
 ```shell
 <prefix> cmd  # Use the default account.
-<prefix> cmd --account 0  # Use first account that would show up in `get_user_selected_account()`.
+<prefix> cmd --account 0  # Use first account that would show up in `select_account()`.
 <prefix> cmd --account metamask  # Use account with alias "metamask".
 <prefix> cmd --account TEST::0  # Use the test account at index 0.
 ```
 
-Alternatively, you can call the [get_user_selected_account()](../methoddocs/cli.html#ape.cli.choices.get_user_selected_account) directly to have more control of when the account gets selected:
+Alternatively, you can call the [select_account()](../methoddocs/cli.html#ape.cli.choices.select_account) directly to have more control of when the account gets selected:
 
 ```python
 import click
@@ -197,7 +197,7 @@ Use `account_type` to filter the choices by specific types of [AccountAPI](../me
 ```python
 import click
 from ape import accounts
-from ape.cli import existing_alias_argument, get_user_selected_account
+from ape.cli import existing_alias_argument, select_account
 from ape_accounts.accounts import KeyfileAccount
 
 # NOTE: This is just an example and not anything specific or recommended.
@@ -215,7 +215,7 @@ def cli_1(alias):
 
 # Select from the given accounts directly.
 my_accounts = [accounts.load("me"), accounts.load("me2")]
-selected_account = get_user_selected_account(account_type=my_accounts)
+selected_account = select_account(account_type=my_accounts)
 ```
 
 ## Contract File Paths

docs/userguides/compile.md

@@ -39,7 +39,9 @@ contract.my_method()
 3. **Raw Compiler Output**: If you have an artifact with binary compiled elsewhere, you can include it in your project.
    This is useful if you want to use contracts from much larger projects as dependency for your test cases.
 
-**WARN**: You may have to adjust name and source ID similarly to raw contract-type output.
+```{warning}
+You may have to adjust name and source ID similarly to raw contract-type output.
+```
 
 ## Other Compiler Plugins
 

docs/userguides/config.md

@@ -15,7 +15,7 @@ Most of the features in this guide are documented more-fully elsewhere in the us
 
 However, here is a list of common-use cases requiring the `ape-config.yaml` file to help you:
 
-1. Setting up a custom node RPC: See the [geth](#geth) section.
+1. Setting up a custom node RPC: See the [node](#node) section.
 2. Setting up project dependencies: See the [dependencies](#dependencies) section.
 3. Declaring your project's plugins: See the [plugins](#plugins) section.
 
@@ -85,23 +85,27 @@ from ape import project
 contract = project.MyContract.deployments[0]
 ```
 
-**NOTE**: Ape does not add or edit deployments in your `ape-config.yaml` file.
+```{note}
+Ape does not add or edit deployments in your `ape-config.yaml` file.
+```
 
-## Geth
+## Node
 
-When using the `geth` provider, you can customize its settings.
+When using the `node` provider, you can customize its settings.
 For example, to change the URI for an Ethereum network, do:
 
 ```yaml
-geth:
+node:
   ethereum:
     mainnet:
       uri: http://localhost:5030
 ```
 
 Now, the `ape-node` core plugin will use the URL `http://localhost:5030` to connect and make requests.
 
-**WARN**: Instead of using `ape-node` to connect to an Infura or Alchemy node, use the [ape-infura](https://github.com/ApeWorX/ape-infura) or [ape-alchemy](https://github.com/ApeWorX/ape-alchemy) provider plugins instead, which have their own way of managing API keys via environment variables.
+```{warning}
+Instead of using `ape-node` to connect to an Infura or Alchemy node, use the [ape-infura](https://github.com/ApeWorX/ape-infura) or [ape-alchemy](https://github.com/ApeWorX/ape-alchemy) provider plugins instead, which have their own way of managing API keys via environment variables.
+```
 
 For more information on networking as a whole, see [this guide](./networks.html).
 
@@ -148,7 +152,9 @@ For the local network configuration, the default is `"max"`. Otherwise, it is `"
 
 Set which `ape` plugins you want to always use.
 
-**NOTE**: The `ape-` prefix is not needed and shouldn't be included here.
+```{note}
+The `ape-` prefix is not needed and shouldn't be included here.
+```
 
 ```yaml
 plugins:

docs/userguides/console.md

@@ -9,8 +9,10 @@ In [1]: chain.blocks.head.timestamp
 Out[1]: 1647323479
 ```
 
-WARNING: Contract changes are not reflected in the active console session.
+```{warning}
+Contract changes are not reflected in the active console session.
 If you need to make changes to your contract, you must re-start your console session for the compiler to handle the changes.
+```
 
 ## Ape Namespace
 
@@ -41,7 +43,10 @@ In [1]: networks
 Out[1]: <NetworkManager active_provider=<test chain_id=61>>
 ```
 
-**NOTE**: To change the network of the active console, use the `--network` option.
+```{note}
+To change the network of the active console, use the `--network` option.
+```
+
 Follow [this guide](./networks.html) for more information on networks in Ape.
 
 ## Namespace Extras

docs/userguides/contracts.md

@@ -10,7 +10,9 @@ The other way is to initialize an already-deployed contract using its address.
 Deploy contracts from your project using the `project` root-level object.
 You deploy contracts using Python functions such as [AccountAPI.deploy](../methoddocs/api.html#ape.api.accounts.AccountAPI.deploy) or [ContractContainer.deploy](../methoddocs/contracts.html#ape.contracts.base.ContractContainer.deploy).
 
-**NOTE**: You can run Ape's deploy functions from anywhere you run Python!
+```{note}
+You can run Ape's deploy functions anywhere you run Python!
+```
 
 You need both an account and a contract in order to deploy a contract, as the deployment process requires a transaction to submit the contract data to the blockchain.
 To learn about accounts and how to use them, see the [Accounts Guide](./accounts.html).
@@ -246,7 +248,9 @@ _ = contract.withdraw(sender=account, value="1 wei")
 
 Notice that transacting returns a [ReceiptAPI](../methoddocs/api.html#ape.api.transactions.ReceiptAPI) object which contains all the receipt data, such as `gas_used`.
 
-**NOTE**: If you need the `return_value` from a transaction, you have to either treat transaction as a call (see the section below!) or use a provider with tracing-features enabled (such as `ape-foundry` or `ape-node`) and access the [return_value](../methoddocs/api.html#ape.api.transactions.ReceiptAPI.return_value) property on the receipt.
+```{note}
+If you need the `return_value` from a transaction, you have to either treat transaction as a call (see the section below!) or use a provider with tracing-features enabled (such as `ape-foundry` or `ape-node`) and access the [return_value](../methoddocs/api.html#ape.api.transactions.ReceiptAPI.return_value) property on the receipt.
+```
 
 ```python
 assert receipt.return_value == 123

docs/userguides/data.md

@@ -51,17 +51,22 @@ See [this guide](../userguides/contracts.html) for more information how to deplo
 
 ## Using the Cache
 
-**Note**: This is in Beta release.
+```{note}
+This is in Beta release.
 This functionality is in constant development and many features are in planning stages.
 Use the cache plugin to store provider data in a sqlite database.
+```
 
 To use the cache, first you must initialize it for each network you plan on caching data for:
 
 ```bash
 ape cache init --network <ecosystem-name>:<network-name>
 ```
 
-**Note**: Caching only works for permanently available networks. It will not work with local development networks.
+```{note}
+Caching only works for permanently available networks. 
+It will not work with local development networks.
+```
 
 For example, to initialize the cache database for the Ethereum mainnet network, you would do the following:
 

docs/userguides/dependencies.md

@@ -9,9 +9,11 @@ There are three sub-folders in `.ape/packages` for dependencies:
    When you compile a dependency, the contract types are stored in the dependency manifest's JSON file.
 3. `api/` - for caching the API data placed in `dependencies:` config or `ape pm install` commands, allowing dependency usage and management from anywhere in the file system.
 
-*NOTE*: You can install dependencies that don't compile out-of-the-box.
+```{note}
+You can install dependencies that don't compile out-of-the-box.
 Sometimes, dependencies are only collections of source files not meant to compile on their own but instead be used in projects via import statements.
 You can change the settings of a dependency using `config_override:` to compile dependencies after installed, if needed, and the `api/` cache always refers to the latest used during installation or compilation.
+```
 
 ## Types of Dependencies
 
@@ -33,8 +35,11 @@ dependencies:
 
 Then, follow the guide below about `remappings` to use the dependency.
 
+```{warning}
 **An important WARNING about the `version:` key for GitHub dependencies:**
 The `version:` config first attempts to use an official GitHub release, but if the release is not found, it will check the release tags.
+```
+
 If you know the version is not available as an official release, bypass the original check by using the `ref:` key.
 The `ref:` key is also used for installing branches.
 
@@ -133,10 +138,12 @@ To install a dependency that is not in your config, you can specify it directly
 ape pm install gh:OpenZeppelin/openzeppelin-contracts --name openzeppelin --version "4.6.0"
 ```
 
-**NOTE**: The `gh:` prefix is used because this dependency is from GitHub.
+```{note}
+The `gh:` prefix is used because this dependency is from GitHub.
 For `npm` dependencies, you use an `npm:` prefix.
 For local dependencies, you give it a path to the local dependency.
 `--version` is not required when using a local dependency.
+```
 
 To change the config of a dependency when installing, use the `--config-override` CLI option:
 
@@ -178,7 +185,9 @@ To skip the confirmation prompts, use the `--yes` flag (abbreviated as `-y`):
 ape pm uninstall OpenZeppelin all --yes
 ```
 
-**NOTE**: Additionally, use the `all` special version key to delete all versions.
+```{note}
+Additionally, use the `all` special version key to delete all versions.
+```
 
 ### compile
 
@@ -194,8 +203,10 @@ You can use the CLI to recompile.
 ape pm compile OpenZeppelin --version 4.6.0 --force
 ```
 
-**NOTE**: You only need to specify a version if you have more than one version of a dependency installed.
+```{note}
+You only need to specify a version if you have more than one version of a dependency installed.
 Otherwise, you just give it the name.
+```
 
 To compile all dependencies in your local project, run the command with no arguments while in your project:
 

docs/userguides/developing_plugins.md

@@ -17,7 +17,11 @@ The following is a list of example plugins to use as a reference when developing
 
 As previously mentioned, a plugin project is merely a python project.
 However, you can optionally use this [project template](https://github.com/ApeWorX/project-template) for initializing your plugin.
-**NOTE**: this template is primarily designed for plugins built within the ApeWorX team organization; not everything may apply.
+
+```{note}
+This template is primarily designed for plugins built within the ApeWorX team organization; not everything may apply.
+```
+
 It is okay to delete anything that does not work or that you don't find helpful.
 The template may be good to follow if you want to keep your plugin of similar quality to plugins developed by the ApeWorX team.
 
@@ -28,7 +32,10 @@ A benefit of the plugin system is that each plugin can implement these however t
 Two plugins with the same API may do entirely different things and yet be interchangeable in their usage.
 
 To implement an API, import its class and use it as a base-class in your implementation class.
-**WARNING**: The plugin will fail to work properly if you do not implement all the abstract methods.
+
+```{warning}
+The plugin will fail to work properly if you do not implement all the abstract methods.
+```
 
 ```python
 from ape.api import ProviderAPI
@@ -96,7 +103,10 @@ entry_points={
 ...
 ```
 
-**NOTE**: Typically, a `_cli.py` module is used instead of a `__init__.py` module for the location of the Click CLI group because it is logically separate from the Python module loading process.
+```{note}
+Typically, a `_cli.py` module is used instead of a `__init__.py` module for the location of the Click CLI group because it is logically separate from the Python module loading process.
+```
+
 If you try to define them together and use `ape` as a library as well, there is a race condition in the loading process that will prevent the CLI plugin from working.
 
 For common `click` usages, use the `ape.cli` namespace.
@@ -133,7 +143,10 @@ Similarly, if you implemented a `ProviderAPI`, that provider is now accessible i
 ape console my_script --network ethereum:local:my_provider_plugin
 ```
 
-**NOTE**: The `--network` option is available on the commands `test` and `console` as well as any CLI command that uses the [network option decorator](../methoddocs/cli.html?highlight=network_option#ape.cli.options.network_option).
+```{note}
+The `--network` option is available on the commands `test` and `console` as well as any CLI command that uses the [network option decorator](../methoddocs/cli.html?highlight=network_option#ape.cli.options.network_option).
+```
+
 To learn more about networks in Ape, follow [this guide](./networks.html).
 
 When creating the CLI-based plugins, you should see your CLI command as a top-level command in the `ape --help` output: