add documentation to device product block

gso/products/product_blocks/__init__.py

+"""Product blocks that store information about subscriptions.
+
+In this file, some enumerators may be declared that are used across multiple subscriptions.
+"""
+
 from enum import Enum
 
 
 class PhyPortCapacity(Enum):
-    ONE = "1g"
-    TEN = "10g"
-    HUNDRED = "100g"
-    FOUR_HUNDRED = "400g"
+    """Physical port capacity enumerator.
+
+    An enumerator that contains the different possible capacities of ports that are available to use in subscriptions.
+    """
+
+    ONE = "1G"
+    """1Gbps"""
+    TEN = "10G"
+    """10Gbps"""
+    HUNDRED = "100G"
+    """100Gbps"""
+    FOUR_HUNDRED = "400G"
+    """400Gbps"""

gso/products/product_blocks/device.py

+"""Product block for {class}`Device` products."""
 import ipaddress
 from typing import Optional
 
@@ -8,19 +9,30 @@ from gso.products.product_blocks.site import SiteBlock, SiteBlockInactive, SiteB
 
 
 class DeviceVendor(strEnum):
-    juniper = "juniper"
-    nokia = "nokia"
+    """Enumerator for the different product vendors that are supported."""
+
+    JUNIPER = "Juniper"
+    """Juniper devices."""
+    NOKIA = "Nokia"
+    """Nokia devices."""
 
 
 class DeviceRole(strEnum):
-    p = "p"
-    pe = "pe"
-    amt = "amt"
+    """Enumerator for the different types of routers."""
+
+    P = "P"
+    """P router."""
+    PE = "PE"
+    """PE router."""
+    AMT = "AMT"
+    """AMT router."""
 
 
 class DeviceBlockInactive(
     ProductBlockModel, lifecycle=[SubscriptionLifecycle.INITIAL], product_block_name="DeviceBlock"
 ):
+    """A device that is being currently inactive. See {class}`DeviceBlock`."""
+
     device_fqdn: Optional[str] = None
     device_ts_address: Optional[str] = None
     device_ts_port: Optional[int] = None
@@ -37,6 +49,8 @@ class DeviceBlockInactive(
 
 
 class DeviceBlockProvisioning(DeviceBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
+    """A device that is being provisioned. See {class}`DeviceBlock`."""
+
     device_fqdn: str
     device_ts_address: str
     device_ts_port: int
@@ -53,16 +67,33 @@ class DeviceBlockProvisioning(DeviceBlockInactive, lifecycle=[SubscriptionLifecy
 
 
 class DeviceBlock(DeviceBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
+    """A device that is currently deployed in the network."""
+
     device_fqdn: str
+    """{term}`FQDN` of a device."""
     device_ts_address: str
+    """The address of the terminal server that this device is connected to. The terminal server provides out of band
+    access. This is required in case a link goes down, or when a device is initially added to the network and it does
+    not have any IP trunks connected to it yet."""
     device_ts_port: int
+    """The port of the terminal server that this device is connected to. Used for the same reason as mentioned above."""
     device_access_via_ts: bool
+    """Whether this device should be accessed through the terminal server, or through its loopback address."""
     device_lo_ipv4_address: ipaddress.IPv4Address
+    """The IPv4 loopback address of the device."""
     device_lo_ipv6_address: ipaddress.IPv6Address
+    """The IPv6 loopback address of the device."""
     device_lo_iso_address: str
+    """The {term}`ISO` {term}`NET` of the device, used for {term}`IS-IS` support."""
     device_si_ipv4_network: ipaddress.IPv4Network
+    """The SI IPv4 network of the device."""
     device_ias_lt_ipv4_network: ipaddress.IPv4Network
+    """The IAS LT IPv4 network of the device."""
     device_ias_lt_ipv6_network: ipaddress.IPv6Network
+    """The IAS LT IPv6 network of the device."""
     device_vendor: DeviceVendor
+    """The vendor of the device, can be any of the values defined in {class}`DeviceVendor`."""
     device_role: DeviceRole
+    """The role of the device, which can be any of the values defined in {class}`DeviceRole`."""
     device_site: SiteBlock
+    """The {class}`Site` that this device resides in. Both physically and computationally."""