diff --git a/.gitignore b/.gitignore index e3eaa624c040da6a8d4b117b4c6b0eeab7c463df..792183231acc09723dd827d600ee40da51b6fe72 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ oss-params.json docs/build docs/vale/styles/* !docs/vale/styles/Vocab/ +!docs/vale/styles/custom/ .idea .venv diff --git a/docs/source/glossary.md b/docs/source/glossary.md index 57fc3374266ee04bcf33e1dd84c02b63005b1031..7035fa3bbb5019fbde57c70deeb66694924ff233 100644 --- a/docs/source/glossary.md +++ b/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 diff --git a/docs/vale/.vale.ini b/docs/vale/.vale.ini index 2982d4d1525c0202c2c176d5fe5f82b0b87f3090..cc1a032a86a01aac5d50a594a348c7fa8a3979f6 100644 --- a/docs/vale/.vale.ini +++ b/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] diff --git a/docs/vale/styles/Vocab/geant-jargon/accept.txt b/docs/vale/styles/Vocab/geant-jargon/accept.txt index b4ae8b012b00eadd3f7108bba81ecbd642057d13..f9dd1b51637ed1b2e93e61c6f3e97be90132b57c 100644 --- a/docs/vale/styles/Vocab/geant-jargon/accept.txt +++ b/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 diff --git a/docs/vale/styles/custom/Contractions.yml b/docs/vale/styles/custom/Contractions.yml new file mode 100644 index 0000000000000000000000000000000000000000..9c2b94a52ad8840de5539565d9e6d4d288cdd838 --- /dev/null +++ b/docs/vale/styles/custom/Contractions.yml @@ -0,0 +1,27 @@ +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 diff --git a/gso/services/infoblox.py b/gso/services/infoblox.py index c8775d0ead11a51b6c7d73143997fba2ed2bda17..fca0965cc75b60c858edaa457ee217939ea598e8 100644 --- a/gso/services/infoblox.py +++ b/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. diff --git a/gso/services/provisioning_proxy.py b/gso/services/provisioning_proxy.py index 1ca12a0b95d8a03da406491f2c4fbcf1af4bc5ca..412902e5a4982927c84d1922c757f664065b87e8 100644 --- a/gso/services/provisioning_proxy.py +++ b/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` diff --git a/gso/services/subscriptions.py b/gso/services/subscriptions.py index 9ee2e4dfa8091ea06ae9e5b1dee947fdc8794156..4986c06af466290ffe62140824830d66dcec4424 100644 --- a/gso/services/subscriptions.py +++ b/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