docs: add documentation (#154)

.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 }}

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:

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")
 

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

docs/conf.py

@@ -0,0 +1 @@
+extensions = ["sphinx_ape"]

docs/index.rst

@@ -0,0 +1 @@
+.. dynamic-toc-tree::

docs/methoddocs/dependency.md

@@ -0,0 +1,7 @@
+# Dependency
+
+```{eval-rst}
+.. automodule:: ape_etherscan.dependency
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/exceptions.md

@@ -0,0 +1,7 @@
+# Exceptions
+
+```{eval-rst}
+.. automodule:: ape_etherscan.exceptions
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/explorer.md

@@ -0,0 +1,7 @@
+# Explorer
+
+```{eval-rst}
+.. automodule:: ape_etherscan.explorer
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/verify.md

@@ -0,0 +1,7 @@
+# Verify
+
+```{eval-rst}
+.. automodule:: ape_etherscan.verify
+    :members:
+    :show-inheritance:
+```

docs/userguides/quickstart.md

@@ -0,0 +1,2 @@
+```{include} ../../README.md
+```

setup.cfg

@@ -1,5 +1,6 @@
 [flake8]
 max-line-length = 100
+ignore = E704,W503,PYD002
 exclude =
 	venv*
 	docs

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