docs: document explorer URL in custom networks (ApeWorX#1867)

docs/userguides/networks.md

@@ -170,6 +170,35 @@ geth:
 
 Now, when using `ethereum:apenet:geth`, it will connect to the RPC URL `https://apenet.example.com/rpc`.
 
+#### Explorer URL
+
+To configure explorer URLs for your custom network, use the explorer's plugin config.
+For example, let's say you added the following network:
+
+```yaml
+networks:
+  custom:
+    - name: customnetwork
+      chain_id: 31337
+      default_provider: geth
+```
+
+To add a corresponding entry in `ape-etherscan` (assuming you are using `ape-etherscan` as your explorer plugin), add the following to your `ape-config.yaml` file:
+
+```yaml
+etherscan:
+  ethereum:
+    rate_limit: 15  # Configure a rate limit that makes sense for retry logic.
+    
+    # The name of the entry is the same as your custom network!
+    customnetwork:
+      uri: https://custom.scan              # URL used for showing transactions
+      api_uri: https://api.custom.scan/api  # URL used for making API requests.
+```
+
+**NOTE**: Every explorer plugin may be different in how you configure custom networks.
+Consult the plugin's README to clarify.
+
 #### Block time, transaction type, and more config
 
 Configuring network properties in Ape is the same regardless of whether it is custom or not.

src/ape/cli/choices.py

@@ -5,7 +5,7 @@
 from typing import Any, Callable, Iterator, List, Optional, Sequence, Type, Union
 
 import click
-from click import BadOptionUsage, BadParameter, Choice, Context, Parameter
+from click import BadParameter, Choice, Context, Parameter
 
 from ape import accounts, networks
 from ape.api.accounts import AccountAPI
@@ -359,13 +359,6 @@ def convert(self, value: Any, param: Optional[Parameter], ctx: Optional[Context]
             # By-pass choice constraints when using custom network.
             choice = value
 
-        elif "custom" in value:
-            raise BadOptionUsage(
-                "--network",
-                "Custom network options must include connection str as well, "
-                "such as the URI. Check `provider.network_choice` (if possible).",
-            )
-
         else:
             # Regular conditions.
             try:

tests/functional/test_cli.py

@@ -1,8 +1,8 @@
+import copy
 import shutil
 
 import click
 import pytest
-from click import BadOptionUsage
 
 from ape.cli import (
     AccountAliasPromptChoice,
@@ -18,6 +18,7 @@
     select_account,
     verbosity_option,
 )
+from ape.cli.choices import _get_networks_sequence_from_cache
 from ape.cli.commands import get_param_from_ctx, parse_network
 from ape.exceptions import AccountsError
 from ape.logging import logger
@@ -644,27 +645,32 @@ def test_network_choice():
 
 
 @pytest.mark.parametrize("prefix", ("", "ethereum:custom:"))
-def test_network_choice_when_custom_network(prefix):
+def test_network_choice_custom_adhoc_network(prefix):
     network_choice = NetworkChoice()
     uri = "https://example.com"
     actual = network_choice.convert(f"{prefix}{uri}", None, None)
     assert actual.uri == uri
     assert actual.network.name == "custom"
 
 
+def test_network_choice_custom_config_network(custom_networks_config_dict, temp_config):
+    data = copy.deepcopy(custom_networks_config_dict)
+
+    # Was a bug where couldn't have this name.
+    data["networks"]["custom"][0]["name"] = "custom"
+
+    _get_networks_sequence_from_cache.cache_clear()
+
+    network_choice = NetworkChoice()
+    with temp_config(data):
+        actual = network_choice.convert("ethereum:custom", None, None)
+
+    assert actual.network.name == "custom"
+
+
 def test_network_choice_when_custom_local_network():
     network_choice = NetworkChoice()
     uri = "https://example.com"
     actual = network_choice.convert(f"ethereum:local:{uri}", None, None)
     assert actual.uri == uri
     assert actual.network.name == "local"
-
-
-def test_network_choice_when_custom_and_missing_provider():
-    network_choice = NetworkChoice()
-    expected = (
-        r"Custom network options must include connection str as well, such as the URI\. "
-        r"Check `provider.network_choice` \(if possible\).*"
-    )
-    with pytest.raises(BadOptionUsage, match=expected):
-        network_choice.convert("ethereum:custom", None, None)