docs: overhaul docs

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: docs
+on:
+  push:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      PUBLISH: ${{ contains(fromJSON('["master", "main"]'), github.ref_name) && 'true' || 'false' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          cache: 'pip'
+      - uses: actions/cache@v4
+        with:
+          key: ${{ github.ref }}  # cache by branch
+          path: .cache
+      - run: pip install -r requirements.txt
+
+      - run: mkdocs build
+        if: env.PUBLISH == 'false'
+
+      - uses: actions/upload-artifact@v4
+        if: env.PUBLISH == 'false'
+        with:
+          name: site
+          path: site
+
+      - run: mkdocs gh-deploy --force
+        if: env.PUBLISH == 'true'

.readthedocs.yaml

@@ -11,9 +11,9 @@ build:
     # rust: "1.64"
     # golang: "1.19"
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-   configuration: docs/source/conf.py
+# Build documentation in the docs/ directory with mkdocs
+mkdocs:
+   configuration: mkdocs.yml
 
 # Explicitly set the version of Python and its requirements
 python:

docs/api/cache.md

@@ -0,0 +1,29 @@
+# Cache
+
+## `set_cache_dir`
+
+!!! function "`boa.interpret.set_cache_dir()`"
+    <a href="https://github.com/vyperlang/titanoboa/blob/v0.2.4/boa/interpret.py#L53-L59" class="source-code-link" target="_blank" rel="noopener"></a>
+
+    **Description**
+
+    Set the cache directory for the Vyper compilation results.
+    By default, this is set to `~/.cache/titanoboa`.
+    In case the directory is `None`, the cache will be disabled.
+
+    ---
+
+    **Parameters**
+
+    - `cache_dir`: The directory to store the cache files.
+
+---
+
+## `disable_cache`
+
+!!! function "`boa.interpret.disable_cache()`"
+    <a href="https://github.com/vyperlang/titanoboa/blob/v0.2.4/boa/interpret.py#L62-L63" class="source-code-link" target="_blank" rel="noopener"></a>
+
+    **Description**
+
+    Set the cache directory for the Vyper compilation results.

docs/api/common_classes/_BaseEVMContract.md

@@ -0,0 +1,30 @@
+# `_BaseEVMContract`
+
+### Description
+
+The `_BaseEVMContract` class provides the base functionality for EVM contracts. It includes methods for handling contract deployment, execution, and interaction.
+
+### Methods
+
+- [stack_trace](stack_trace.md)
+- [call_trace](call_trace.md)
+- [handle_error](handle_error.md)
+
+### Properties
+
+- [address](address.md)
+
+### Examples
+
+```python
+>>> import boa
+>>> src = """
+... @external
+... def main():
+...     pass
+... """
+>>> deployer = boa.loads_partial(src, name="Foo")
+>>> contract = deployer.deploy()
+>>> type(contract)
+<class 'boa.vyper.contract.VyperContract'>
+```

docs/api/common_classes/_BaseVyperContract.md

@@ -0,0 +1,26 @@
+# `_BaseVyperContract`
+
+### Description
+
+The `_BaseVyperContract` class extends `_BaseEVMContract` and provides additional functionality specific to Vyper contracts. It includes methods for handling Vyper-specific features such as ABI encoding/decoding, event handling, and more.
+
+### Methods
+
+- [deployer](deployer.md)
+- [abi](abi.md)
+- [_constants](_constants.md)
+
+### Examples
+
+```python
+>>> import boa
+>>> src = """
+... @external
+... def main():
+...     pass
+... """
+>>> deployer = boa.loads_partial(src, name="Foo")
+>>> contract = deployer.deploy()
+>>> type(contract)
+<class 'boa.vyper.contract.VyperContract'>
+```

docs/api/common_classes/_constants.md

@@ -0,0 +1,27 @@
+# `_constants`
+
+### Property
+
+```python
+@property
+_constants: ConstantsModel
+```
+
+### Description
+
+Provides access to the constants defined in the Vyper contract.
+
+- Returns: A `ConstantsModel` instance.
+
+### Examples
+
+```python
+>>> import boa
+>>> src = """
+... x: constant(uint256) = 123
+... """
+>>> deployer = boa.loads_partial(src, name="Foo")
+>>> contract = deployer.deploy()
+>>> contract._constants.x
+123
+```

docs/api/common_classes/abi.md

@@ -0,0 +1,30 @@
+# `abi`
+
+### Property
+
+```python
+@property
+abi: dict
+```
+
+### Description
+
+Returns the ABI (Application Binary Interface) of the Vyper contract.
+
+- Returns: A dictionary representing the ABI of the contract.
+
+### Examples
+
+```python
+>>> import boa
+>>> src = """
+... @external
+... def main():
+...     pass
+... """
+>>> deployer = boa.loads_partial(src, name="Foo")
+>>> contract = deployer.deploy()
+>>> contract_abi = contract.abi
+>>> type(contract_abi)
+<class 'dict'>
+```

docs/api/common_classes/call_trace.md

@@ -0,0 +1,33 @@
+# `call_trace`
+
+<!-- TODO: Format this with !!!function syntax -->
+
+### Signature
+
+```python
+call_trace() -> TraceFrame
+```
+
+### Description
+
+Returns the call trace of the computation.
+
+- Returns: A `TraceFrame` instance.
+
+### Examples
+
+!!! python
+
+    ```python
+    >>> import boa
+    >>> src = """
+    ... @external
+    ... def main():
+    ...     pass
+    ... """
+    >>> deployer = boa.loads_partial(src, name="Foo")
+    >>> contract = deployer.deploy()
+    >>> contract.main()
+    >>> contract.call_trace()
+    <TraceFrame ...>
+    ```

docs/api/common_classes/handle_error.md

@@ -0,0 +1 @@
+TODO

docs/api/common_classes/stack_trace.md

@@ -0,0 +1,33 @@
+# `stack_trace`
+
+### Signature
+
+```python
+stack_trace(computation: ComputationAPI) -> StackTrace
+```
+
+### Description
+
+Returns the stack trace of the computation.
+
+- `computation`: The computation to get the stack trace for.
+- Returns: A `StackTrace` instance.
+
+### Examples
+
+```python
+>>> import boa
+>>> src = """
+... @external
+... def main():
+...     assert False, "error"
+... """
+>>> deployer = boa.loads_partial(src, name="Foo")
+>>> contract = deployer.deploy()
+>>> try:
+...     contract.main()
+... except:
+...     pass
+>>> contract.stack_trace(contract._computation)
+<StackTrace ...>
+```

docs/api/env/browser_env.md

@@ -0,0 +1,5 @@
+# BrowserEnv
+
+Inherits: [`NetworkEnv`](network_env.md)
+
+<!-- TODO: Document BrowserEnv API -->