From 4c57a8f2f3ea43d18df34d6d86c26e734fc014e5 Mon Sep 17 00:00:00 2001 From: antazoey Date: Tue, 15 Oct 2024 15:07:29 -0500 Subject: [PATCH] docs: add documentation (#154) --- .github/workflows/docs.yaml | 34 ++++++++++++++++++++++++++++++++++ ape_etherscan/explorer.py | 20 ++++++++++++++++++++ ape_etherscan/types.py | 2 +- ape_etherscan/verify.py | 26 ++++++++++++++++++++++++++ docs/conf.py | 1 + docs/index.rst | 1 + docs/methoddocs/dependency.md | 7 +++++++ docs/methoddocs/exceptions.md | 7 +++++++ docs/methoddocs/explorer.md | 7 +++++++ docs/methoddocs/verify.md | 7 +++++++ docs/userguides/quickstart.md | 2 ++ setup.cfg | 1 + setup.py | 6 +----- 13 files changed, 115 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/methoddocs/dependency.md create mode 100644 docs/methoddocs/exceptions.md create mode 100644 docs/methoddocs/explorer.md create mode 100644 docs/methoddocs/verify.md create mode 100644 docs/userguides/quickstart.md diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..ade497b --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,34 @@ +name: Docs + +on: + push: + branches: [main] + release: + types: [released] + pull_request: + types: [opened, synchronize] + +jobs: + docs: + runs-on: ubuntu-latest + + permissions: + contents: write + + steps: + - uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: "3.10" + + - name: Install Dependencies + run: | + python -m pip install --upgrade pip + pip install .[doc] + + - name: Ape Etherscan Docs + uses: apeworx/sphinx-ape@main + with: + github-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/ape_etherscan/explorer.py b/ape_etherscan/explorer.py index 04ff391..29c17ad 100644 --- a/ape_etherscan/explorer.py +++ b/ape_etherscan/explorer.py @@ -21,18 +21,28 @@ class Etherscan(ExplorerAPI): + """ + The explorer API implemention for Etherscan. + """ + @property def _config(self) -> PluginConfig: return self.config_manager.get_config("etherscan") @property def etherscan_uri(self): + """ + The base URL of the explorer. + """ return get_etherscan_uri( self._config, self.network.ecosystem.name, self.network.name.replace("-fork", "") ) @property def etherscan_api_uri(self): + """ + The base URL for the API service. + """ return get_etherscan_api_uri( self._config, self.network.ecosystem.name, self.network.name.replace("-fork", "") ) @@ -55,6 +65,16 @@ def _client_factory(self) -> ClientFactory: ) def get_manifest(self, address: AddressType) -> Optional[PackageManifest]: + """ + Get a package manifest. + + Args: + address (AddressType): The address of a contract. + + Returns: + ethpm_types.PackageManifest | None: None when the contract is not + published. + """ try: response = self._get_source_code(address) except ContractNotVerifiedError: diff --git a/ape_etherscan/types.py b/ape_etherscan/types.py index 30c3587..e32a532 100644 --- a/ape_etherscan/types.py +++ b/ape_etherscan/types.py @@ -30,7 +30,7 @@ class SourceCodeResponse(BaseModel): evm_version: str = Field(default="Default", alias="EVMVersion") library: str = Field(default="", alias="Library") license_type: str = Field(default="", alias="LicenseType") - proxy: bool = Field(False, alias="Proxy") + proxy: bool = Field(default=False, alias="Proxy") implementation: str = Field(default="", alias="Implementation") swarm_source: str = Field(default="", alias="SwarmSource") diff --git a/ape_etherscan/verify.py b/ape_etherscan/verify.py index 34c491b..c5af833 100644 --- a/ape_etherscan/verify.py +++ b/ape_etherscan/verify.py @@ -174,10 +174,21 @@ def from_spdx_id(cls, spdx_id: str) -> "LicenseType": class VerificationApproach(Enum): STANDARD_JSON = "STANDARD_JSON" + """ + The standard input JSON approach. + """ + FLATTEN = "FLATTEN" + """ + The flattened contract approach. + """ class SourceVerifier(ManagerAccessMixin): + """ + A class for verifying contract sources. + """ + def __init__( self, address: AddressType, @@ -198,22 +209,37 @@ def contract_client(self) -> ContractClient: @cached_property def contract(self) -> ContractInstance: + """ + The ape contract instance to verify. + """ return self.chain_manager.contracts.instance_at(self.address) @property def contract_type(self) -> ContractType: + """ + The ethpm-types ContractType to verify. + """ return self.contract.contract_type @property def contract_name(self) -> str: + """ + The name of the contract. + """ return self.contract.contract_type.name or "" @property def source_path(self) -> Path: + """ + The path to the contract, locally. + """ return self.project.path / (self.contract_type.source_id or "") @property def ext(self) -> str: + """ + The source path extension. + """ return self.source_path.suffix @cached_property diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..9181c1d --- /dev/null +++ b/docs/conf.py @@ -0,0 +1 @@ +extensions = ["sphinx_ape"] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b559066 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1 @@ +.. dynamic-toc-tree:: diff --git a/docs/methoddocs/dependency.md b/docs/methoddocs/dependency.md new file mode 100644 index 0000000..ddc66a4 --- /dev/null +++ b/docs/methoddocs/dependency.md @@ -0,0 +1,7 @@ +# Dependency + +```{eval-rst} +.. automodule:: ape_etherscan.dependency + :members: + :show-inheritance: +``` diff --git a/docs/methoddocs/exceptions.md b/docs/methoddocs/exceptions.md new file mode 100644 index 0000000..d4942ed --- /dev/null +++ b/docs/methoddocs/exceptions.md @@ -0,0 +1,7 @@ +# Exceptions + +```{eval-rst} +.. automodule:: ape_etherscan.exceptions + :members: + :show-inheritance: +``` diff --git a/docs/methoddocs/explorer.md b/docs/methoddocs/explorer.md new file mode 100644 index 0000000..b8badf4 --- /dev/null +++ b/docs/methoddocs/explorer.md @@ -0,0 +1,7 @@ +# Explorer + +```{eval-rst} +.. automodule:: ape_etherscan.explorer + :members: + :show-inheritance: +``` diff --git a/docs/methoddocs/verify.md b/docs/methoddocs/verify.md new file mode 100644 index 0000000..6feedc1 --- /dev/null +++ b/docs/methoddocs/verify.md @@ -0,0 +1,7 @@ +# Verify + +```{eval-rst} +.. automodule:: ape_etherscan.verify + :members: + :show-inheritance: +``` diff --git a/docs/userguides/quickstart.md b/docs/userguides/quickstart.md new file mode 100644 index 0000000..c7719d8 --- /dev/null +++ b/docs/userguides/quickstart.md @@ -0,0 +1,2 @@ +```{include} ../../README.md +``` diff --git a/setup.cfg b/setup.cfg index 1c2ef4d..84f6a9e 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,6 @@ [flake8] max-line-length = 100 +ignore = E704,W503,PYD002 exclude = venv* docs diff --git a/setup.py b/setup.py index 93ff17b..a425f02 100644 --- a/setup.py +++ b/setup.py @@ -36,11 +36,7 @@ "mdformat-frontmatter>=0.4.1", # Needed for frontmatters-style headers in issue templates "mdformat-pyproject>=0.0.1", # Allows configuring in pyproject.toml ], - "doc": [ - "Sphinx>=6.1.3,<7", # Documentation generator - "sphinx_rtd_theme>=1.2.0,<2", # Readthedocs.org theme - "towncrier>=19.2.0,<20", # Generate release notes - ], + "doc": ["sphinx-ape"], "release": [ # `release` GitHub Action job uses this "setuptools", # Installation tool "setuptools-scm", # Installation tool