update documentation

gso/products/product_blocks/router.py

@@ -78,7 +78,7 @@ class RouterBlock(RouterBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTI
     router_fqdn: str
     """{term}`FQDN` of a router."""
     router_ts_port: PortNumber
-    """The port of the terminal server that this router is connected to. Used to provide out of band access."""
+    """The port of the terminal server that this router is connected to. Used to offer out of band access."""
     router_access_via_ts: bool
     """Whether this router should be accessed through the terminal server, or through its loopback address."""
     router_lo_ipv4_address: ipaddress.IPv4Address

gso/products/product_blocks/site.py

@@ -10,8 +10,8 @@ from pydantic import ConstrainedStr
 class SiteTier(strEnum):
     """The tier of a site, ranging from 1 to 4.
 
-    A lower value generally corresponds to a larger amount of installed equipment, and a higher cardinality of the
-    connectivity to and from a site.
+    A lower value corresponds to a larger amount of installed equipment, and a higher cardinality of the connectivity to
+    and from a site.
     """
 
     TIER1 = 1
@@ -21,7 +21,7 @@ class SiteTier(strEnum):
 
 
 class SnmpCoordinate(ConstrainedStr):
-    """An SNMP coordinate, modeled as a constrained string.
+    """An {term}`SNMP` coordinate, modeled as a constrained string.
 
     The coordinate must match the format of `1.35`, `-12.3456`, etc.
     """

gso/products/product_types/__init__.py

 """Product types define the different products that are available.
 
-Multiple product blocks may insist on a single product type. In that sense, a product type is a mode general description
-of a product. For example, the product type {class}`Router` must either be a router or a switch, both being separate
-product blocks.
+More than one product block may insist on a single product type. In that sense, a product type is a more general
+description of a product.
 """

gso/services/resource_manager.py

@@ -6,7 +6,7 @@ from gso import settings
 
 # TODO
 # - fill in the implementations
-# - consider the additional API methods
+# - consider the extra API methods
 # - decided what to do with various error conditions (currently assertions)
 
 
@@ -101,8 +101,8 @@ def free_physical_interface(router_fqdn: str, interface_name: str, oss_params=se
     # TODO: this is a dummy implementation
 
     ifc = _find_physical(router_fqdn, interface_name)
-    # TODO: is this really an error that should be handled?
-    #  ... or is it ok to ignore this?
+    # TODO: is this truly an error that should be handled?
+    # or is it ok to ignore this?
     assert (
         ifc["state"] != InterfaceAllocationState.AVAILABLE
     ), f"interface {router_fqdn}:{interface_name} is already available"

gso/workflows/utils.py

@@ -15,10 +15,10 @@ def customer_selector() -> Choice:
 
 
 def iso_from_ipv4(ipv4_address: IPv4Address) -> str:
-    """Calculate an ISO address, based on an IPv4 address.
+    """Calculate an {term}`ISO` address, based on an IPv4 address.
 
-    :param IPv4Address ipv4_address: The address that is to be converted
-    :returns: An ISO-formatted address.
+    :param IPv4Address ipv4_address: The address that's to be converted
+    :returns: An {term}`ISO`-formatted address.
     """
     padded_octets = [f"{x:>03}" for x in str(ipv4_address).split(".")]
     joined_octets = "".join(padded_octets)