fix: add more detailed instructions to README (#68)

* fix: README walkthrough with more detailed instructions for getting started

* fix: format of md file

* feat: remove running tests if no changes occur

* fix: remove comment for changes to the tests.yaml file

* fix: revert workflows

* docs: update section about distributed execution

* refactor: updates from peer review

* fix: use admonition

---------

Co-authored-by: doggie <[email protected]>

README.md

@@ -13,7 +13,7 @@ Some examples of these types of applications:
 
 ## Documentation
 
-Read the [development userguide](https://docs.apeworx.io/silverback/stable/userguides/development.html) to learn more how to develop an application.
+Please read the [development userguide](https://docs.apeworx.io/silverback/stable/userguides/development.html) for more information on how to develop an application.
 
 ## Dependencies
 
@@ -23,6 +23,10 @@ Read the [development userguide](https://docs.apeworx.io/silverback/stable/userg
 
 Silverback relies heavily on the Ape development framework, so it's worth it to familarize yourself with how to install Ape and it's plugins using the [Ape installation userguide](https://docs.apeworx.io/ape/latest/userguides/quickstart#installation).
 
+```{note}
+It is suggested that you use a virtual environment of your choosing, and then install the Silverback package via one of the following options.
+```
+
 ### via `pip`
 
 You can install the latest release via [`pip`](https://pypi.org/project/pip/):
@@ -45,24 +49,89 @@ python3 setup.py install
 
 Checkout [the example](./example.py) to see how to use the library.
 
-To run your bot against a live network, this SDK includes a simple runner you can use via:
+```{note}
+The example makes use of the [Ape Tokens](https://github.com/ApeWorX/ape-tokens) plugin.
+Be sure to properly configure your environment for the USDC and YFI tokens on Ethereum mainnet.
+```
+
+To run your bot against a live network, this SDK includes a simple runner command you can use via:
 
 ```sh
 $ silverback run "example:app" --network :mainnet:alchemy
 ```
 
-**NOTE**: The example is designed to work with Python 3.10+, and we suggest using 3.11+ for speed.
+```{note}
+This runner uses an in-memory task broker by default.
+If you want to learn more about what that means, please visit the [development userguide](https://docs.apeworx.io/silverback/stable/userguides/development.html).
+```
 
 ## Docker Usage
 
 ```sh
+$ docker run --volume $PWD:/home/harambe/project --volume ~/.tokenlists:/home/harambe/.tokenlists apeworx/silverback:latest run "example:app" --network :mainnet
+```
+
+```{note}
+The Docker image we publish uses Python 3.11.
+```
+
+## Setting Up Your Environment
+
+Running the `Quick Usage` and `Docker Usage` with the provided example will fail if you do not have a fully-configured environment.
+Most common issues when using the SDK stem from the proper configuration of Ape plugins to unlock the behavior you desire.
+
+You should use a provider that supports websockets to run silverback.
+If you want to use a hosted provider with websocket support like Alchemy to run this example, you will need a Alchemy API key for Ethereum mainnet.
+If you attempt to run the `Docker Usage` command without supplying this key, you will get the following error:
+
+```bash
 $ docker run --volume $PWD:/home/harambe/project --volume ~/.tokenlists:/home/harambe/.tokenlists apeworx/silverback:latest run "example:app" --network :mainnet:alchemy
+Traceback (most recent call last):
+  ...
+ape_alchemy.exceptions.MissingProjectKeyError: Must set one of $WEB3_ALCHEMY_PROJECT_ID, $WEB3_ALCHEMY_API_KEY, $WEB3_ETHEREUM_MAINNET_ALCHEMY_PROJECT_ID, $WEB3_ETHEREUM_MAINNET_ALCHEMY_API_KEY.
 ```
 
-**NOTE**: The Docker image we publish uses Python 3.11
+Go to [Alchemy](https://alchemy.com), create an account, then create an application in their dashboard, and copy the API Key.
+
+Another requirement for the command from `Docker Usage` to run the given example is that it uses [ape-tokens](https://github.com/ApeWorX/ape-tokens) plugin to look up token interfaces by symbol.
+In order for this to work, you should have installed and configured that plugin using a token list that includes both YFI and USDC on Ethereum mainnet.
+Doing this will give you a `~/.tokenlists` hidden folder in your home folder that you must mount into the docker container with the following flag:
+
+```bash
+... --volume ~/.tokenlists:/home/harambe/.tokenlists ...
+```
+
+```{note}
+It is suggested to install the 1inch tokenlist via `ape tokens install tokens.1inch.eth`.
+See the [ape-tokens](https://github.com/ApeWorX/ape-tokens?tab=readme-ov-file#quick-usage) README for more information.
+```
+
+To check that both of the tokens exist in your configured tokenlist, you can execute this command:
+
+```bash
+$ ape tokens token-info YFI
+      Symbol: YFI
+        Name: yearn.finance
+    Chain ID: 1
+     Address: 0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e
+    Decimals: 18
+
+$ ape tokens token-info USDC
+      Symbol: USDC
+        Name: Circle USD
+    Chain ID: 1
+     Address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
+    Decimals: 6
+```
+
+```{note}
+If you want, you can comment out the two functions `exec_event1` and `exec_event2` that handle the contract log events from these contracts if you do not have the configured tokenlist, then your command should work.
+```
 
 ## Development
 
-This project is in development and should be considered a beta.
+This project is under active development in preparation of the release of the [Silverback Platform](https://silverback.apeworx.io).
 Things might not be in their final state and breaking changes may occur.
 Comments, questions, criticisms and pull requests are welcomed.
+
+See [Contributing](https://github.com/ApeWorX/silverback/blob/main/CONTRIBUTING.md) for more information.

docs/userguides/development.md

@@ -141,22 +141,32 @@ else:
     # Log what the transaction *would* have done, had a signer been enabled
 ```
 
-```note
+```{note}
 If you configure your application to use a signer, and that signer signs anything given to it, remember that you can lose substational amounts of funds if you deploy this to a production network.
 Always test your applications throughly before deploying.
 ```
 
 ### Distributed Execution
 
-Using only the `silverback run ...` command in a defualt configuration executes everything in one process and the job queue is completely in-memory with a shared state.  In some high volume environments, you may want to deploy your Silverback application in a distributed configuration using multiple processes to handle the messages at a higher rate.
+Using only the `silverback run ...` command in a default configuration executes everything in one process and the job queue is completely in-memory with a shared state.
+In some high volume environments, you may want to deploy your Silverback application in a distributed configuration using multiple processes to handle the messages at a higher rate.
 
 The primary components are the client and workers.  The client handles Silverback events (blocks and contract event logs) and creates jobs for the workers to process in an asynchronous manner.
 
-For this to work, you must configure a [TaskIQ broker](https://taskiq-python.github.io/guide/architecture-overview.html#broker) capable of distributed processing.  For instance, with [`taskiq_redis`](https://github.com/taskiq-python/taskiq-redis) you could do something like this for the client:
+For this to work, you must configure a [TaskIQ broker](https://taskiq-python.github.io/guide/architecture-overview.html#broker) capable of distributed processing.
+Additonally, it is highly suggested you should also configure a [TaskIQ result backend](https://taskiq-python.github.io/guide/architecture-overview.html#result-backend) in order to process and store the results of executing tasks.
+
+```{note}
+Without configuring a result backend, Silverback may not work as expected since your tasks will now suddenly return `None` instead of the actual result.
+```
+
+For instance, with [`taskiq_redis`](https://github.com/taskiq-python/taskiq-redis) you could do something like this for the client:
 
 ```bash
 export SILVERBACK_BROKER_CLASS="taskiq_redis:ListQueueBroker"
 export SILVERBACK_BROKER_KWARGS='{"queue_name": "taskiq", "url": "redis://127.0.0.1:6379"}'
+export SILVERBACK_RESULT_BACKEND_CLASS="taskiq_redis:RedisAsyncResultBackend"
+export SILVERBACK_RESULT_BACKEND_URI="redis://127.0.0.1:6379"
 
 silverback run "example:app" --network :mainnet:alchemy
 ```
@@ -166,6 +176,8 @@ And then the worker process with 2 worker subprocesses:
 ```bash
 export SILVERBACK_BROKER_CLASS="taskiq_redis:ListQueueBroker"
 export SILVERBACK_BROKER_KWARGS='{"url": "redis://127.0.0.1:6379"}'
+export SILVERBACK_RESULT_BACKEND_CLASS="taskiq_redis:RedisAsyncResultBackend"
+export SILVERBACK_RESULT_BACKEND_URI="redis://127.0.0.1:6379"
 
 silverback worker -w 2 "example:app"
 ```