add docs for miner factory and miner network

docs/miner_factory.md

@@ -0,0 +1,8 @@
+# pyasic
+## Miner Factory
+
+::: pyasic.miners.miner_factory.MinerFactory
+    handler: python
+    options:
+        show_root_heading: false
+        heading_level: 4

docs/miner_network.md

@@ -0,0 +1,11 @@
+# pyasic
+## Miner Network
+
+
+
+
+::: pyasic.network.MinerNetwork
+    handler: python
+    options:
+        show_root_heading: false
+        heading_level: 4

mkdocs.yml

@@ -2,7 +2,11 @@ site_name: pyasic
 repo_url: https://github.com/UpstreamData/pyasic
 nav:
   - Introduction: "index.md"
-  - API: "api.md"
+  - Usage:
+      - Miner Factory: "miner_factory.md"
+      - Miner Network: "miner_network.md"
+  - Advanced:
+      - API: "api.md"
 
 plugins:
   - mkdocstrings

pyasic/miners/miner_factory.py

@@ -1,4 +1,4 @@
-from typing import TypeVar, Tuple, List
+from typing import TypeVar, Tuple, List, Union
 from collections.abc import AsyncIterable
 from pyasic.miners import BaseMiner
 
@@ -10,9 +10,9 @@ from pyasic.miners._backends.cgminer import CGMiner  # noqa - Ignore _module imp
 from pyasic.miners._backends.bmminer import BMMiner  # noqa - Ignore _module import
 from pyasic.miners._backends.bosminer import BOSMiner  # noqa - Ignore _module import
 from pyasic.miners._backends.btminer import BTMiner  # noqa - Ignore _module import
-from pyasic.miners._backends.bosminer_old import (
+from pyasic.miners._backends.bosminer_old import (  # noqa - Ignore _module import
     BOSMinerOld,
-)  # noqa - Ignore _module import
+)
 
 from pyasic.miners.unknown import UnknownMiner
 
@@ -229,11 +229,13 @@ class Singleton(type):
 
 
 class MinerFactory(metaclass=Singleton):
+    """A factory to handle identification and selection of the proper class of miner"""
+
     def __init__(self) -> None:
         self.miners = {}
 
     async def get_miner_generator(
-        self, ips: List[ipaddress.ip_address or str]
+        self, ips: List[Union[ipaddress.ip_address, str]]
     ) -> AsyncIterable[AnyMiner]:
         """
         Get Miner objects from ip addresses using an async generator.
@@ -242,6 +244,9 @@ class MinerFactory(metaclass=Singleton):
 
         Parameters:
             ips: a list of ip addresses to get miners for.
+
+        Returns:
+            An async iterable containing miners.
         """
         # get the event loop
         loop = asyncio.get_event_loop()
@@ -256,8 +261,15 @@ class MinerFactory(metaclass=Singleton):
         for miner in scanned:
             yield await miner
 
-    async def get_miner(self, ip: ipaddress.ip_address or str) -> AnyMiner:
+    async def get_miner(self, ip: Union[ipaddress.ip_address, str]) -> AnyMiner:
-        """Decide a miner type using the IP address of the miner."""
+        """Decide a miner type using the IP address of the miner.
+
+        Parameters:
+            ip: An `ipaddress.ip_address` or string of the IP to find the miner.
+
+        Returns:
+            A miner class.
+        """
         if isinstance(ip, str):
             ip = ipaddress.ip_address(ip)
         # check if the miner already exists in cache

pyasic/network/__init__.py

@@ -12,12 +12,27 @@ from pyasic.settings import (
 
 
 class MinerNetwork:
+    """A class to handle a network containing miners. Handles scanning and gets miners via [`MinerFactory`][pyasic.miners.miner_factory.MinerFactory].
+
+    Parameters:
+        ip_addr: ### An IP address, range of IP addresses, or a list of IPs
+            * Takes a single IP address as an `ipadddress.ipaddress()` or a string
+            * Takes a string formatted as:
+            ```f"{ip_range_1_start}-{ip_range_1_end}, {ip_address_1}, {ip_range_2_start}-{ip_range_2_end}, {ip_address_2}..."```
+            * Also takes a list of strings or `ipaddress.ipaddress` formatted as:
+            ```[{ip_address_1}, {ip_address_2}, {ip_address_3}, ...]```
+        mask: A subnet mask to use when constructing the network.  Only used if `ip_addr` is a single IP.
+            Defaults to /24 (255.255.255.0 or 0.0.0.255)
+    """
+
     def __init__(
         self, ip_addr: str or None = None, mask: str or int or None = None
     ) -> None:
         self.network = None
         self.ip_addr = ip_addr
         self.connected_miners = {}
+        if mask.startswith("/"):
+            mask = mask.replace("/", "")
         self.mask = mask
 
     def __len__(self):

pyasic/network/net_range.py

@@ -5,12 +5,12 @@ import ipaddress
 class MinerNetworkRange:
     """A MinerNetwork that takes a range of IP addresses.
 
-    :param ip_range: A range of IP addresses to put in the network, or a list of IPs
+    Parameters:
-        Takes a string formatted as:
+        ip_range: ## A range of IP addresses to put in the network, or a list of IPs
-            {ip_range_1_start}-{ip_range_1_end}, {ip_address_1},
+            * Takes a string formatted as:
-            {ip_range_2_start}-{ip_range_2_end}, {ip_address_2}...
+                * {ip_range_1_start}-{ip_range_1_end}, {ip_address_1}, {ip_range_2_start}-{ip_range_2_end}, {ip_address_2}...
-        Also takes a list of strings formatted as:
+            * Also takes a list of strings formatted as:
-            [{ip_address_1}, {ip_address_2}, {ip_address_3}, ...]
+                * [{ip_address_1}, {ip_address_2}, {ip_address_3}, ...]
     """
 
     def __init__(self, ip_range: Union[str, list]):