Update Vale linting and documentation to be more in line with the general GAP documentation

.gitignore

@@ -14,6 +14,7 @@ oss-params.json
 docs/build
 docs/vale/styles/*
 !docs/vale/styles/Vocab/
+!docs/vale/styles/custom/
 
 .idea
 .venv

docs/source/glossary.md

@@ -5,6 +5,9 @@ BGP
 : Border Gateway Protocol: a path vector routing protocol described in 
 <a href="https://datatracker.ietf.org/doc/html/rfc4271" target="_blank">RFC 4271</a>.
 
+CNAME
+: A type of DNS record that is used as an alias from one hostname to another
+
 CRUD
 : Create, Read, Update, Delete
 

docs/vale/.vale.ini

@@ -20,13 +20,16 @@ proselint.Annotations = NO
 ; Replacing a ... with … shouldn't be holding back the entire CI pipeline
 proselint.Typography = warning
 ; Same applies for not using contractions
-Microsoft.Contractions = warning
+Microsoft.Contractions = NO
+custom.Contractions = YES
 
 TokenIgnores = ({term}), (:param \S+:), (:type \S+:)
 
 [*/glossary.md]
 ; Ignore acronyms being undefined in the file that defines all acronyms by definition.
 Microsoft.Acronyms = NO
+Microsoft.Contractions = NO
+custom.Contractions = YES
 Microsoft.Passive = NO
 
 [formats]

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

@@ -10,3 +10,4 @@ dry_run
 Dark_fiber
 [A|a]ddress
 [I|i]ptrunk
+[A|a]llocate

docs/vale/styles/custom/Contractions.yml

+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: suggestion
+ignorecase: true
+swap:
+  aren't: are not
+  can't: cannot
+  couldn't: could not
+  didn't: did not
+  don't: do not
+  doesn't: does not
+  hasn't: has not
+  haven't: have not
+  how's: how is
+  isn't: is not
+  it's: it is
+  shouldn't: should not
+  that's: that is
+  they're: they are
+  wasn't: was not
+  we're: we are
+  we've: we have
+  weren't: were not
+  what's: what is
+  when's: when is
+  where's: where is
+  won't: will not

gso/services/infoblox.py

@@ -20,7 +20,7 @@ class DeletionError(Exception):
 def _setup_connection() -> tuple[connector.Connector, IPAMParams]:
     """Set up a new connection with an Infoblox instance.
 
-    :return: A tuple that contains an Infoblox `Connector` instance, and
+    :return: A tuple that has an Infoblox `Connector` instance, and {term}`IPAM` parameters.
     :rtype: tuple[{class}`infoblox_client.connector.Connector`, IPAMParams]
     """
     oss = load_oss_params().IPAM
@@ -52,7 +52,8 @@ def _allocate_network(
     :type dns_view: str
     :param netmask: The netmask of the desired network. Can be up to 32 for v4 networks, and 128 for v6 networks.
     :type netmask: int
-    :param containers: A list of network containers in which the network should be allocated, given in CIDR notation.
+    :param containers: A list of network containers in which the network should be allocated, given in {term}`CIDR`
+                       notation.
     :type containers: list[str]
     :param comment: Optionally, a comment can be added to the network allocation.
     :type comment: str, optional
@@ -85,8 +86,8 @@ def hostname_available(hostname: str) -> bool:
 def allocate_v4_network(service_type: str, comment: str | None = "") -> ipaddress.IPv4Network:
     """Allocate a new IPv4 network in Infoblox.
 
-    Allocate an IPv4 network for a specific service type. The service type should be defined in the OSS parameters of
-    GSO, from which the containers and netmask will be used.
+    Allocate an IPv4 network for a specific service type. The service type should be defined in the {term}`OSS`
+    parameters of {term}`GSO`, from which the containers and netmask will be used.
 
     :param service_type: The service type for which the network is allocated.
     :type service_type: str
@@ -104,8 +105,8 @@ def allocate_v4_network(service_type: str, comment: str | None = "") -> ipaddres
 def allocate_v6_network(service_type: str, comment: str | None = "") -> ipaddress.IPv6Network:
     """Allocate a new IPv6 network in Infoblox.
 
-    Allocate an IPv6 network for a specific service type. The service type should be defined in the OSS parameters of
-    GSO, from which the containers and netmask will be used.
+    Allocate an IPv6 network for a specific service type. The service type should be defined in the {term}`OSS`
+    parameters of {term}`GSO`, from which the containers and netmask will be used.
 
     :param service_type: The service type for which the network is allocated.
     :type service_type: str
@@ -123,8 +124,8 @@ def allocate_v6_network(service_type: str, comment: str | None = "") -> ipaddres
 def delete_network(ip_network: ipaddress.IPv4Network | ipaddress.IPv6Network) -> None:
     """Delete a network in Infoblox.
 
-    Delete a network that is allocated in Infoblox, by passing the CIDR to be deleted. The CIDR must exactly match an
-    existing entry in Infoblox, otherwise this method raises a {class}`DeletionError`
+    Delete a network that is allocated in Infoblox, by passing the {term}`CIDR` to be deleted. The {term}`CIDR` must
+    exactly match an existing entry in Infoblox, otherwise this method raises a {class}`DeletionError`
 
     :param ip_network: The network that should get deleted.
     :type ip_network: ipaddress.IPv4Network | ipaddress.IPv6Network
@@ -146,12 +147,12 @@ def allocate_host(
     host. Most likely to be a loopback interface. If the hostname is not available in Infoblox (due to a potential
     collision) this method raises an {class}`AllocationError`.
 
-    :param hostname: The FQDN of the new host
+    :param hostname: The {term}`FQDN` of the new host
     :type hostname: str
     :param service_type: The service type from which IP resources should be used.
     :type service_type: str
-    :param cname_aliases: A list of any CNAME aliases that should be associated with this host. Most often this will
-                          be a single loopback address.
+    :param cname_aliases: A list of any {term}`CNAME` aliases that should be associated with this host. Most often this
+                          will be a single loopback address.
     :type cname_aliases: list[str]
     :param comment: Optionally, a comment can be added to the host record in Infoblox.
     :type comment: str, optional
@@ -218,7 +219,7 @@ def delete_host_by_ip(ip_addr: ipaddress.IPv4Address | ipaddress.IPv6Address) ->
 def delete_host_by_fqdn(fqdn: str) -> None:
     """Delete a host from Infoblox.
 
-    Delete a host record in Infoblox, by providing the FQDN that is associated with the record. Raises a
+    Delete a host record in Infoblox, by providing the {term}`FQDN` that is associated with the record. Raises a
     {class}`DeletionError` if no record can be found in Infoblox.
 
     :param fqdn: The FQDN of the host record that should get deleted.

gso/services/provisioning_proxy.py

@@ -29,7 +29,7 @@ DEFAULT_LABEL = "Provisioning proxy is running. Please come back later for the r
 class CUDOperation(strEnum):
     """Enumerator for different {term}`CRUD` operations that the provisioning proxy supports.
 
-    Read isn't applicable, hence the missing R.
+    Read is not applicable, hence the missing R.
     """
 
     POST = "POST"
@@ -173,7 +173,7 @@ def migrate_ip_trunk(
     :type new_node: {class}`Router`
     :param new_lag_interface: The name of the new aggregated Ethernet interface
     :type new_lag_interface: str
-    :param new_lag_member_interfaces: The new list of interfaces that are part of the LAG
+    :param new_lag_member_interfaces: The new list of interfaces that are part of the {term}`LAG`
     :type new_lag_member_interfaces: list[str]
     :param replace_index: The index of the side that is going to be replaced as part of the existing trunk,
                           can be `0` or `1`.
@@ -213,7 +213,7 @@ def _await_pp_results(subscription: SubscriptionModel, label_text: str = DEFAULT
 
     :param subscription: The current subscription that the provisioning proxy is acting on.
     :type subscription: {class}`orchestrator.domain.SubscriptionModel`
-    :param label_text: A label that's displayed to the operator when the provisioning proxy hasn't returned its
+    :param label_text: A label that's displayed to the operator when the provisioning proxy has not returned its
         results yet. Defaults to `DEFAULT_LABEL`.
     :type label_text: str
     :return: The input that's given by the provisioning proxy, that should contain run results, and a `confirm`

gso/services/subscriptions.py

@@ -69,7 +69,7 @@ def get_active_router_subscriptions(fields: list[str]) -> list[Subscription]:
 
 
 def get_product_id_by_name(product_name: ProductType) -> UUID:
-    """Retrieve the UUID of a product by its name.
+    """Retrieve the {term}`UUID` of a product by its name.
 
     Args:
     ----
@@ -77,7 +77,7 @@ def get_product_id_by_name(product_name: ProductType) -> UUID:
 
     Returns:
     -------
-    UUID: The UUID of the product.
+    {term}`UUID`: The {term}`UUID` of the product.
     """
     return ProductTable.query.filter_by(name=product_name).first().product_id