resolve Vale linting warnings and suggestions, updating docs

docs/source/glossary.md

@@ -10,6 +10,9 @@ FQDN
 GSO
 : GÉANT Service Orchestrator
 
+IPAM
+: IP Address Management
+
 IS-IS
 : Intermediate System to Intermediate System: a routing protocol described in 
 <a href="https://datatracker.ietf.org/doc/html/rfc7142" target="_blank">RFC 7142</a>.

docs/vale/styles/Vocab/geant-jargon/accept.txt

@@ -8,3 +8,4 @@ Ansible
 API
 dry_run
 Dark_fiber
+[A|a]ddress

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.
+In this file, some enumerators may be declared that are available for use across all subscriptions.
 """
 
 from enum import Enum
@@ -9,7 +9,7 @@ from enum import Enum
 class PhyPortCapacity(Enum):
     """Physical port capacity enumerator.
 
-    An enumerator that contains the different possible capacities of ports that are available to use in subscriptions.
+    An enumerator that has the different possible capacities of ports that are available to use in subscriptions.
     """
 
     ONE = "1G"

gso/products/product_blocks/device.py

@@ -76,7 +76,8 @@ class DeviceBlock(DeviceBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTI
     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."""
+    """The port of the terminal server that this device is connected to. Used for the same reason as mentioned
+    previously."""
     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

gso/services/_ipam.py

@@ -246,7 +246,7 @@ def _allocate_host(
     if couldn't allocate host due to requested network not existing.
     """
     # TODO: should hostnames be unique
-    # (i.e. fail if hostname already exists in this domain/service)?
+    # (that is, fail if hostname already exists in this domain/service)?
     assert addrs or networks, "You must specify either the host addresses or the networks CIDR."
     oss = settings.load_oss_params()
     assert oss.IPAM.INFOBLOX
@@ -563,7 +563,7 @@ def delete_service_host(
     assert "_ref" in host_data[0]
     host_ref = host_data[0]["_ref"]
 
-    # Find cname records reference
+    # Find CNAME records reference
     r = requests.get(
         f"{_wapi(infoblox_params)}/record:cname",
         params={

gso/services/provisioning_proxy.py

@@ -44,7 +44,8 @@ class CUDOperation(strEnum):
 def _send_request(endpoint: str, parameters: dict, process_id: UUIDstr, operation: CUDOperation) -> None:
     """Send a request to {term}`LSO`. The callback address is derived using the process ID provided.
 
-    :param endpoint: The {term}`LSO`-specific endpoint to call, depending on the type of service object that's acted upon.
+    :param endpoint: The {term}`LSO`-specific endpoint to call, depending on the type of service object that's acted
+        upon.
     :type endpoint: str
     :param parameters: JSON body for the request, which will almost always at least consist of a subscription object,
         and a boolean value to indicate a dry run.

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 additional API methods
 # - decided what to do with various error conditions (currently assertions)
 
 

gso/settings.py

-"""GSO settings.
+"""{term}`GSO` settings.
 
 Ensuring that the required parameters are set correctly.
 """
@@ -14,11 +14,11 @@ logger = logging.getLogger(__name__)
 
 
 class GeneralParams(BaseSettings):
-    """General parameters for a GSO configuration file."""
+    """General parameters for a {term}`GSO` configuration file."""
 
-    #: The hostname that GSO is publicly served at, used for building the
-    #: callback URL that the provisioning proxy uses.
     public_hostname: str
+    """The hostname that {term}`GSO` is publicly served at, used for building the callback URL that the provisioning
+    proxy uses."""
 
 
 class InfoBloxParams(BaseSettings):
@@ -60,7 +60,7 @@ class ServiceNetworkParams(BaseSettings):
 
 
 class IPAMParams(BaseSettings):
-    """A set of parameters related to IPAM."""
+    """A set of parameters related to {term}`IPAM`."""
 
     INFOBLOX: InfoBloxParams
     LO: ServiceNetworkParams
@@ -86,7 +86,7 @@ class ResourceManagementParams(BaseSettings):
 
 
 class OSSParams(BaseSettings):
-    """The set of parameters required for running GSO."""
+    """The set of parameters required for running {term}`GSO`."""
 
     GENERAL: GeneralParams
     IPAM: IPAMParams

gso/workflows/__init__.py

-"""init class that imports all workflows into GSO."""
+"""Initialisation class that imports all workflows into {term}`GSO`."""
 from orchestrator.workflows import LazyWorkflowInstance
 
 LazyWorkflowInstance("gso.workflows.device.create_device", "create_device")

gso/workflows/device/get_facts.py

@@ -20,15 +20,6 @@ def initial_input_form_generator(subscription_id: UUIDstr) -> InputForm:
 @step("Get facts")
 def get_facts(subscription_id: UUIDstr) -> dict:
     subscription = Device.from_subscription(subscription_id)
-    # import ansible_runner
-    #
-    # r = ansible_runner.run(
-    #     private_data_dir="/opt",
-    #     playbook="get_facts.yaml",
-    #     inventory=subscription.device.device_fqdn,
-    # )
-    # out = r.stdout.read()
-    # out_splitted = out.splitlines()
 
     return {"output": subscription}
 

gso/workflows/iptrunk/create_iptrunk.py

@@ -18,7 +18,7 @@ from gso.services.provisioning_proxy import pp_interaction
 
 
 def initial_input_form_generator(product_name: str) -> FormGenerator:
-    # TODO: we need additional validation:
+    # TODO: implement more strict validation:
     # * interface names must be validated
 
     devices = {}
@@ -62,7 +62,7 @@ def initial_input_form_generator(product_name: str) -> FormGenerator:
 
     user_input_side_a = yield CreateIptrunkSideAForm
 
-    # We remove the selected device for side A, to prevent any loops
+    # Remove the selected device for side A, to prevent any loops
     devices.pop(str(user_input_side_a.iptrunk_sideA_node_id.name))
     DeviceEnumB = Choice("Select a device", zip(devices.keys(), devices.items()))  # type: ignore