Skip to content

Commit

Permalink
docs: add method docs
Browse files Browse the repository at this point in the history
  • Loading branch information
dtdang committed Aug 10, 2022
1 parent 048574f commit 538efa5
Show file tree
Hide file tree
Showing 17 changed files with 862 additions and 21 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ $ ape plugins list
```

* Python Version: x.x.x
* OS: osx/linux/win
* OS: macOS/linux/win

### What went wrong?

Expand Down
4 changes: 3 additions & 1 deletion .github/workflows/commitlint.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
56 changes: 56 additions & 0 deletions .github/workflows/docs.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
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 }}
14 changes: 10 additions & 4 deletions .github/workflows/test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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 .
Expand All @@ -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 .

Expand All @@ -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
Expand Down
13 changes: 2 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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).
13 changes: 13 additions & 0 deletions ape_alchemy/providers.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ class AlchemyFeatureNotAvailable(AlchemyProviderError):


class MissingProjectKeyError(AlchemyProviderError):
"""
An error raised when not using one of the options available.
"""

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}.")
Expand All @@ -48,6 +52,15 @@ class AlchemyEthereumProvider(Web3Provider, UpstreamProvider):

@property
def uri(self):
"""
Build from `ecosystem` and `network`.
`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:
Expand Down
86 changes: 86 additions & 0 deletions build_docs.py
Original file line number Diff line number Diff line change
@@ -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()
Loading

0 comments on commit 538efa5

Please sign in to comment.