improve documentation

docs/data/error_codes.md

@@ -23,3 +23,11 @@
     options:
         show_root_heading: false
         heading_level: 4
+<br>
+
+## Innosilicon Error Codes
+::: pyasic.data.error_codes.InnosiliconError
+    handler: python
+    options:
+        show_root_heading: false
+        heading_level: 4

docs/index.md

@@ -101,3 +101,133 @@ async def gather_miner_data():  # define async scan function to allow awaiting
 if __name__ == "__main__":
     asyncio.run(gather_miner_data())
 ```
+
+<br>
+
+## Controlling miners via pyasic
+Every miner class in pyasic must implement all the control functions defined in [`BaseMiner`][pyasic.miners.BaseMiner].
+
+These functions are
+[`check_light`](#check-light),
+[`fault_light_off`](#fault-light-off),
+[`fault_light_on`](#fault-light-on),
+[`get_config`](#get-config),
+[`get_data`](#get-data),
+[`get_errors`](#get-errors),
+[`get_hostname`](#get-hostname),
+[`get_model`](#get-model),
+[`reboot`](#reboot),
+[`restart_backend`](#restart-backend), and
+[`send_config`](#send-config).
+
+<br>
+
+### Check Light
+::: pyasic.miners.BaseMiner.check_light
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Fault Light Off
+::: pyasic.miners.BaseMiner.fault_light_off
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Fault Light On
+::: pyasic.miners.BaseMiner.fault_light_on
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Get Config
+::: pyasic.miners.BaseMiner.get_config
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Get Data
+::: pyasic.miners.BaseMiner.get_data
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Get Errors
+::: pyasic.miners.BaseMiner.get_errors
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Get Hostname
+::: pyasic.miners.BaseMiner.get_hostname
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Get Model
+::: pyasic.miners.BaseMiner.get_model
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Reboot
+::: pyasic.miners.BaseMiner.reboot
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Restart Backend
+::: pyasic.miners.BaseMiner.restart_backend
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+### Send Config
+::: pyasic.miners.BaseMiner.send_config
+    handler: python
+    options:
+        heading_level: 4
+
+<br>
+
+## [`MinerConfig`][pyasic.config.MinerConfig] and [`MinerData`][pyasic.data.MinerData]
+
+Pyasic implements a few dataclasses as helpers to make data return types consistent across different miners and miner APIs.
+
+<br>
+
+### [`MinerData`][pyasic.data.MinerData]
+
+[`MinerData`][pyasic.data.MinerData] is a return from the [`get_data()`](#get-data) function, and is used to have a consistent dataset across all returns.
+
+You can call [`MinerData.asdict()`][pyasic.data.MinerData.asdict] to get the dataclass as a dictionary, and there are many other helper functions contained in the class to convert to different data formats.
+
+<br>
+
+### [`MinerConfig`][pyasic.config.MinerConfig]
+
+[`MinerConfig`][pyasic.config.MinerConfig] is pyasic's way to represent a configuration file from a miner.
+It is the return from [`get_config()`](#get-config).
+
+Each miner has a unique way to convert the [`MinerConfig`][pyasic.config.MinerConfig] to their specific type, there are helper functions in the class.
+In most cases these helper functions should not be used, as [`send_config()`](#send-config) takes a [`MinerConfig`][pyasic.config.MinerConfig] and will do the conversion to the right type for you.

mkdocs.yml

@@ -11,7 +11,6 @@ nav:
           - BTMiner: "miners/backends/btminer.md"
           - CGMiner: "miners/backends/cgminer.md"
           - Hiveon: "miners/backends/hiveon.md"
-
       - Classes:
           - Antminer X9: "miners/antminer/X9.md"
           - Antminer X17: "miners/antminer/X17.md"
@@ -23,14 +22,12 @@ nav:
           - Whatsminer M2X: "miners/whatsminer/M2X.md"
           - Whatsminer M3X: "miners/whatsminer/M3X.md"
           - Innosilicon T3X: "miners/innosilicon/T3X.md"
-
   - Network:
       - Miner Network: "network/miner_network.md"
       - Miner Network Range: "network/miner_network_range.md"
-  - Data:
+  - Dataclasses:
       - Miner Data: "data/miner_data.md"
       - Error Codes: "data/error_codes.md"
-  - Config:
       - Miner Config: "config/miner_config.md"
   - Advanced:
       - Miner APIs:

pyasic/data/__init__.py

@@ -175,15 +175,33 @@ class MinerData:
     def efficiency(self, val):
         pass
 
-    def asdict(self):
+    def asdict(self) -> dict:
+        """Get this dataclass as a dictionary.
+
+        Returns:
+            A dictionary version of this class.
+        """
         return asdict(self)
 
-    def as_json(self):
+    def as_json(self) -> str:
+        """Get this dataclass as JSON.
+
+        Returns:
+            A JSON version of this class.
+        """
         data = self.asdict()
         data["datetime"] = str(int(time.mktime(data["datetime"].timetuple())))
         return json.dumps(data)
 
-    def as_influxdb(self, measurement_name: str = "miner_data"):
+    def as_influxdb(self, measurement_name: str = "miner_data") -> str:
+        """Get this dataclass as [influxdb line protocol](https://docs.influxdata.com/influxdb/v2.4/reference/syntax/line-protocol/).
+
+        Parameters:
+            measurement_name: The name of the measurement to insert into in influxdb.
+
+        Returns:
+            A influxdb line protocol version of this class.
+        """
         tag_data = [measurement_name]
         field_data = []
 

pyasic/miners/base.py

@@ -16,10 +16,16 @@ import asyncssh
 import logging
 import ipaddress
 from abc import ABC, abstractmethod
-from typing import TypeVar
+from typing import TypeVar, List, Union
 
 from pyasic.data import MinerData
 from pyasic.config import MinerConfig
+from pyasic.data.error_codes import (
+    WhatsminerError,
+    BraiinsOSError,
+    InnosiliconError,
+    X19Error,
+)
 
 
 class BaseMiner(ABC):
@@ -85,50 +91,113 @@ class BaseMiner(ABC):
 
     @abstractmethod
     async def fault_light_on(self) -> bool:
+        """Turn the fault light of the miner on and return success as a boolean.
+
+        Returns:
+            A boolean value of the success of turning the light on.
+        """
         pass
 
     @abstractmethod
     async def fault_light_off(self) -> bool:
+        """Turn the fault light of the miner off and return success as a boolean.
+
+        Returns:
+            A boolean value of the success of turning the light off.
+        """
         pass
 
     @abstractmethod
     async def check_light(self) -> bool:
+        """Check the status and return on or off as a boolean.
+
+        Returns:
+            A boolean value where `True` represents on and `False` represents off.
+        """
         pass
 
     @abstractmethod
     async def get_config(self) -> MinerConfig:
+        """Get the mining configuration of the miner and return it as a [`MinerConfig`][pyasic.config.MinerConfig].
+
+        Returns:
+            A [`MinerConfig`][pyasic.config.MinerConfig] containing the pool information and mining configuration.
+        """
         pass
 
     @abstractmethod
     async def get_hostname(self) -> str:
+        """Get the hostname of the miner and return it as a string.
+
+        Returns:
+            A string representing the hostname of the miner.
+        """
         pass
 
     @abstractmethod
     async def get_model(self) -> str:
+        """Get the model of the miner and return it as a string.
+
+        Returns:
+            A string representing the model of the miner.
+        """
         pass
 
     @abstractmethod
     async def reboot(self) -> bool:
+        """Reboot the miner and return success as a boolean.
+
+        Returns:
+            A boolean value of the success of rebooting the miner.
+        """
         pass
 
     @abstractmethod
     async def restart_backend(self) -> bool:
+        """Restart the mining process of the miner (bosminer, bmminer, cgminer, etc) and return success as a boolean.
+
+        Returns:
+            A boolean value of the success of restarting the mining process.
+        """
         pass
 
     @abstractmethod
     async def send_config(self, config: MinerConfig, user_suffix: str = None) -> None:
+        """Set the mining configuration of the miner.
+
+        Parameters:
+            config: A [`MinerConfig`][pyasic.config.MinerConfig] containing the mining config you want to switch the miner to.
+            user_suffix: A suffix to append to the username when sending to the miner.
+        """
         return None
 
     @abstractmethod
     async def get_mac(self) -> str:
+        """Get the MAC address of the miner and return it as a string.
+
+        Returns:
+            A string representing the MAC address of the miner.
+        """
         pass
 
     @abstractmethod
-    async def get_errors(self) -> list:
+    async def get_errors(
+        self,
+    ) -> List[Union[WhatsminerError, BraiinsOSError, InnosiliconError, X19Error]]:
+        """Get a list of the errors the miner is experiencing.
+
+        Returns:
+            A list of error classes representing different errors.
+        """
         pass
 
     @abstractmethod
     async def get_data(self) -> MinerData:
+        """Get data from the miner in the form of [`MinerData`][pyasic.data.MinerData].
+
+        Returns:
+            A [`MinerData`][pyasic.data.MinerData] instance containing data from the miner.
+        """
         return MinerData(ip=str(self.ip))