docs: add method docs

.github/ISSUE_TEMPLATE/bug.md

@@ -16,7 +16,7 @@ $ ape plugins list
 ```
 
 * Python Version: x.x.x
-* OS: osx/linux/win
+* OS: macOS/linux/win
 
 ### What went wrong?
 

.github/workflows/commitlint.yaml

@@ -19,7 +19,9 @@ jobs:
               python-version: 3.8
 
         - name: Install Dependencies
-          run: pip install .[dev]
+          run: |
+            python -m pip install --upgrade pip
+            pip install .[dev]
 
         - name: Check commit history
           run: cz check --rev-range $(git rev-list --all --reverse | head -1)..HEAD

.github/workflows/docs.yaml

@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+    push:
+        branches: [main]
+    release:
+        types: [released]
+    pull_request:
+        types: [opened, synchronize]
+
+jobs:
+    docs:
+        runs-on: ubuntu-latest
+
+        steps:
+        - uses: actions/checkout@v2
+
+        - name: Setup Python
+          uses: actions/setup-python@v2
+          with:
+              python-version: 3.8
+
+        - name: Install Dependencies
+          run: |
+            python -m pip install --upgrade pip
+            pip install .[docs]
+        - name: Build HTML artifact
+          run: python build_docs.py
+
+        - name: Upload HTML artifact
+          uses: actions/upload-artifact@v1
+          with:
+              name: DocumentationHTML
+              path: docs/_build/ape-alchemy
+
+        - name: Commit and publish documentation changes to gh-pages branch
+          run: |
+              if [[ "${GITHUB_EVENT_NAME}" =~ "pull_request" ]]; then
+                echo "skipping 'git commit' step for PR"
+              else
+                git clone https://github.com/${GITHUB_REPOSITORY} --branch gh-pages --single-branch gh-pages
+                cp -r docs/_build/ape-alchemy/* gh-pages/
+                cd gh-pages
+                touch .nojekyll
+                git config --local user.email "[email protected]"
+                git config --local user.name "GitHub Action"
+                git add .
+                git commit -m "Update documentation" -a || true
+              fi
+        - name: Push changes
+          uses: ad-m/github-push-action@master
+          if: ${{ github.event_name != 'pull_request' }}
+          with:
+              branch: gh-pages
+              directory: gh-pages
+              github_token: ${{ secrets.GITHUB_TOKEN }}
+

.github/workflows/test.yaml

@@ -15,7 +15,9 @@ jobs:
               python-version: 3.8
 
         - name: Install Dependencies
-          run: pip install .[lint]
+          run: |
+            python -m pip install --upgrade pip
+            pip install .[lint]
 
         - name: Run Black
           run: black --check .
@@ -38,8 +40,10 @@ jobs:
               python-version: 3.8
 
         - name: Install Dependencies
-          run: pip install .[lint,test]  # Might need test deps
-
+          run: |
+            python -m pip install --upgrade pip
+            pip install .[lint,test]
+
         - name: Run MyPy
           run: mypy .
 
@@ -60,7 +64,9 @@ jobs:
               python-version: ${{ matrix.python-version }}
 
         - name: Install Dependencies
-          run: pip install .[test]
+          run: |
+            python -m pip install --upgrade pip
+            pip install .[test]
 
         - name: Run Tests
           run: pytest -m "not fuzzing" -n 0 -s --cov

README.md

@@ -1,10 +1,10 @@
-# Ape Alchemy Plugin
+# Quick Start
 
 [Alchemy](https://alchemy.com/?r=jk3NDM0MTIwODIzM) Provider plugin for Ethereum-based networks.
 
 ## Dependencies
 
-* [python3](https://www.python.org/downloads) version 3.7 or greater, python3-dev
+* [python3](https://www.python.org/downloads) version 3.7.2 or greater, python3-dev
 
 ## Installation
 
@@ -102,12 +102,3 @@ root_node_kwargs = {
 trace_frame_iter = alchemy.get_transaction_trace(txn_hash)
 call_tree = get_calltree_from_geth_trace(trace_frame_iter)
 ```
-
-## Development
-
-Please see the [contributing guide](CONTRIBUTING.md) to learn more how to contribute to this project.
-Comments, questions, criticisms and pull requests are welcomed.
-
-## License
-
-This project is licensed under the [Apache 2.0](LICENSE).

ape_alchemy/exceptions.py

@@ -0,0 +1,26 @@
+from typing import Tuple
+
+from ape.exceptions import ProviderError
+
+
+class AlchemyProviderError(ProviderError):
+    """
+    An error raised by the Alchemy provider plugin.
+    """
+
+
+class AlchemyFeatureNotAvailable(AlchemyProviderError):
+    """
+    An error raised when trying to use a feature that is unavailable
+    on the user's tier or network.
+    """
+
+
+class MissingProjectKeyError(AlchemyProviderError):
+    """
+    An error raised when there is no API key set.
+    """
+
+    def __init__(self, options: Tuple[str, ...]):
+        env_var_str = ", ".join([f"${n}" for n in options])
+        super().__init__(f"Must set one of {env_var_str}.")

ape_alchemy/providers.py

@@ -1,5 +1,5 @@
 import os
-from typing import Any, Dict, Iterator, Tuple
+from typing import Any, Dict, Iterator
 
 from ape.api import UpstreamProvider, Web3Provider
 from ape.exceptions import ContractLogicError, ProviderError, VirtualMachineError
@@ -10,32 +10,15 @@
 from web3.gas_strategies.rpc import rpc_gas_price_strategy
 from web3.middleware import geth_poa_middleware
 
+from .exceptions import AlchemyFeatureNotAvailable, AlchemyProviderError, MissingProjectKeyError
+
 _ETH_ENVIRONMENT_VARIABLE_NAMES = ("WEB3_ALCHEMY_PROJECT_ID", "WEB3_ALCHEMY_API_KEY")
 _ARB_ENVIRONMENT_VARIABLE_NAMES = (
     "WEB3_ARBITRUM_ALCHEMY_PROJECT_ID",
     "WEB3_ARBITRUM_ALCHEMY_API_KEY",
 )
 
 
-class AlchemyProviderError(ProviderError):
-    """
-    An error raised by the Alchemy provider plugin.
-    """
-
-
-class AlchemyFeatureNotAvailable(AlchemyProviderError):
-    """
-    An error raised when trying to use a feature that is unavailable
-    on the user's tier or network.
-    """
-
-
-class MissingProjectKeyError(AlchemyProviderError):
-    def __init__(self, options: Tuple[str, ...]):
-        env_var_str = ", ".join([f"${n}" for n in options])
-        super().__init__(f"Must set one of {env_var_str}.")
-
-
 class AlchemyEthereumProvider(Web3Provider, UpstreamProvider):
     """
     A web3 provider using an HTTP connection to Alchemy.
@@ -47,6 +30,15 @@ class AlchemyEthereumProvider(Web3Provider, UpstreamProvider):
 
     @property
     def uri(self):
+        """
+         Your Alchemy RPC URI, including the project ID.
+
+        `ecosystem`: choose from supported ecosystems
+        `network`: choose a network to connect to
+
+        Returns:
+            str: uri
+        """
         ecosystem_name = self.network.ecosystem.name
         network_name = self.network.name
         if (ecosystem_name, network_name) in self.network_uris:

build_docs.py

@@ -0,0 +1,86 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+REDIRECT_HTML = """
+<!DOCTYPE html>
+<meta charset="utf-8">
+<title>Redirecting...</title>
+<meta http-equiv="refresh" content="0; URL=./{}/">
+"""
+DOCS_BUILD_PATH = Path("docs/_build/ape-alchemy")
+LATEST_PATH = DOCS_BUILD_PATH / "latest"
+STABLE_PATH = DOCS_BUILD_PATH / "stable"
+
+
+class DocsBuildError(Exception):
+    pass
+
+
+def git(*args):
+    return subprocess.check_output(["git", *args]).decode("ascii").strip()
+
+
+def new_dir(path: Path) -> Path:
+    if path.exists():
+        shutil.rmtree(path)
+
+    path.mkdir(parents=True)
+    return path
+
+
+def build_docs(path: Path) -> Path:
+    path = new_dir(path)
+
+    try:
+        subprocess.check_call(["sphinx-build", "docs", str(path)])
+    except subprocess.SubprocessError as err:
+        raise DocsBuildError(f"Command 'sphinx-build docs {path}' failed.") from err
+
+    return path
+
+
+def main():
+    """
+    There are three GH events we build for:
+    1. Push to main: we build into 'latest/'.
+       The GH action will commit these changes to the 'gh-pages' branch.
+    2. Release: we copy 'latest/' into the release dir, as well as to 'stable/'.
+       The GH action will commit these changes to the 'gh-pages' branch.
+    3. Pull requests or local development: We ensure a successful build.
+    """
+
+    event_name = os.environ.get("GITHUB_EVENT_NAME")
+    is_ephemeral = event_name in ["pull_request", None]
+
+    if event_name == "push" or is_ephemeral:
+        build_docs(LATEST_PATH)
+    elif event_name == "release":
+        tag = git("describe", "--tag")
+        if not tag:
+            raise DocsBuildError("Unable to find release tag.")
+
+        if "beta" not in tag and "alpha" not in tag:
+            build_dir = DOCS_BUILD_PATH / tag
+            build_docs(build_dir)
+
+            # Clean-up unnecessary extra 'fonts/' directories to save space.
+            # There should still be one in 'latest/'
+            for font_dirs in build_dir.glob("**/fonts"):
+                if font_dirs.exists():
+                    shutil.rmtree(font_dirs)
+
+            shutil.copytree(build_dir, STABLE_PATH)
+        else:
+            build_docs(STABLE_PATH)
+
+    # Set up the redirect at /index.html
+    DOCS_BUILD_PATH.mkdir(exist_ok=True, parents=True)
+    with open(DOCS_BUILD_PATH / "index.html", "w") as f:
+        redirect = "latest" if is_ephemeral else "stable"
+        f.write(REDIRECT_HTML.format(redirect))
+
+
+if __name__ == "__main__":
+    main()