From f944b960c2c418552046c84d30b94a3696858f69 Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Thu, 11 Jan 2024 17:22:18 +0100
Subject: [PATCH] update documentation, include missing workflows and glossary
entries
---
docs/source/glossary.rst | 4 ++--
docs/source/module/workflows/iptrunk/deploy_twamp.rst | 6 ++++++
docs/source/module/workflows/iptrunk/index.rst | 2 ++
.../module/workflows/iptrunk/validate_iptrunk.rst | 6 ++++++
docs/source/module/workflows/router/index.rst | 1 +
.../source/module/workflows/router/validate_router.rst | 6 ++++++
gso/workflows/iptrunk/deploy_twamp.py | 10 +++++-----
gso/workflows/iptrunk/migrate_iptrunk.py | 4 ++--
gso/workflows/iptrunk/validate_iptrunk.py | 4 ++--
gso/workflows/router/create_router.py | 4 ++--
gso/workflows/router/validate_router.py | 4 ++--
11 files changed, 36 insertions(+), 15 deletions(-)
create mode 100644 docs/source/module/workflows/iptrunk/deploy_twamp.rst
create mode 100644 docs/source/module/workflows/iptrunk/validate_iptrunk.rst
create mode 100644 docs/source/module/workflows/router/validate_router.rst
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
index 5a090e7e..6ac6193a 100644
--- a/docs/source/glossary.rst
+++ b/docs/source/glossary.rst
@@ -27,7 +27,7 @@ Glossary of terms
Create, Read, Update, Delete
DNS
- Domain Name System
+ The Domain Name System. Used for correlating domain names to IP information, among others.
FQDN
Fully Quantified Domain Name
@@ -83,7 +83,7 @@ Glossary of terms
and monitoring.
TWAMP
- Two-way Active Measurement Protocol.
+ A Two-Way Active Measuring Protocol, as defined in `RFC 5357 <https://datatracker.ietf.org/doc/html/rfc5357>`_.
UUID
Universally Unique Identifier
diff --git a/docs/source/module/workflows/iptrunk/deploy_twamp.rst b/docs/source/module/workflows/iptrunk/deploy_twamp.rst
new file mode 100644
index 00000000..7fde1303
--- /dev/null
+++ b/docs/source/module/workflows/iptrunk/deploy_twamp.rst
@@ -0,0 +1,6 @@
+``gso.workflows.iptrunk.deploy_twamp``
+======================================
+
+.. automodule:: gso.workflows.iptrunk.deploy_twamp
+ :members:
+ :show-inheritance:
diff --git a/docs/source/module/workflows/iptrunk/index.rst b/docs/source/module/workflows/iptrunk/index.rst
index 127d1985..12e21b26 100644
--- a/docs/source/module/workflows/iptrunk/index.rst
+++ b/docs/source/module/workflows/iptrunk/index.rst
@@ -15,8 +15,10 @@ Submodules
activate_iptrunk
create_imported_iptrunk
create_iptrunk
+ deploy_twamp
import_iptrunk
migrate_iptrunk
modify_isis_metric
modify_trunk_interface
terminate_iptrunk
+ validate_iptrunk
diff --git a/docs/source/module/workflows/iptrunk/validate_iptrunk.rst b/docs/source/module/workflows/iptrunk/validate_iptrunk.rst
new file mode 100644
index 00000000..c009f8f7
--- /dev/null
+++ b/docs/source/module/workflows/iptrunk/validate_iptrunk.rst
@@ -0,0 +1,6 @@
+``gso.workflows.iptrunk.validate_iptrunk``
+==========================================
+
+.. automodule:: gso.workflows.iptrunk.validate_iptrunk
+ :members:
+ :show-inheritance:
diff --git a/docs/source/module/workflows/router/index.rst b/docs/source/module/workflows/router/index.rst
index 19131578..3e086871 100644
--- a/docs/source/module/workflows/router/index.rst
+++ b/docs/source/module/workflows/router/index.rst
@@ -20,3 +20,4 @@ Submodules
redeploy_base_config
terminate_router
update_ibgp_mesh
+ validate_router
diff --git a/docs/source/module/workflows/router/validate_router.rst b/docs/source/module/workflows/router/validate_router.rst
new file mode 100644
index 00000000..3b44def2
--- /dev/null
+++ b/docs/source/module/workflows/router/validate_router.rst
@@ -0,0 +1,6 @@
+``gso.workflows.router.validate_router``
+========================================
+
+.. automodule:: gso.workflows.router.validate_router
+ :members:
+ :show-inheritance:
diff --git a/gso/workflows/iptrunk/deploy_twamp.py b/gso/workflows/iptrunk/deploy_twamp.py
index c8342f9a..10970127 100644
--- a/gso/workflows/iptrunk/deploy_twamp.py
+++ b/gso/workflows/iptrunk/deploy_twamp.py
@@ -1,4 +1,4 @@
-"""Workflow for adding TWAMP to an existing IP trunk."""
+"""Workflow for adding :term:`TWAMP` to an existing IP trunk."""
import json
@@ -39,7 +39,7 @@ def _initial_input_form_generator(subscription_id: UUIDstr) -> FormGenerator:
@step("[DRY RUN] Deploy TWAMP on both sides")
def deploy_twamp_dry(subscription: Iptrunk, process_id: UUIDstr, callback_route: str, tt_number: str) -> State:
- """Perform a dry run of deploying the TWAMP session."""
+ """Perform a dry run of deploying the :term:`TWAMP` session."""
extra_vars = {
"subscription": json.loads(json_dumps(subscription)),
"process_id": process_id,
@@ -60,7 +60,7 @@ def deploy_twamp_dry(subscription: Iptrunk, process_id: UUIDstr, callback_route:
@step("[FOR REAL] Deploy TWAMP on both sides")
def deploy_twamp_real(subscription: Iptrunk, process_id: UUIDstr, callback_route: str, tt_number: str) -> State:
- """Deploy the TWAMP session."""
+ """Deploy the :term:`TWAMP` session."""
extra_vars = {
"subscription": json.loads(json_dumps(subscription)),
"process_id": process_id,
@@ -103,9 +103,9 @@ def check_twamp_status(subscription: Iptrunk, callback_route: str) -> State:
target=Target.MODIFY,
)
def deploy_twamp() -> StepList:
- """Deploy a TWAMP session on an IP trunk.
+ """Deploy a :term:`TWAMP` session on an IP trunk.
- * Run the TWAMP playbook, including an initial dry run
+ * Run the :term:`TWAMP` playbook, including an initial dry run
"""
return (
init
diff --git a/gso/workflows/iptrunk/migrate_iptrunk.py b/gso/workflows/iptrunk/migrate_iptrunk.py
index a9229493..b0dfb950 100644
--- a/gso/workflows/iptrunk/migrate_iptrunk.py
+++ b/gso/workflows/iptrunk/migrate_iptrunk.py
@@ -182,7 +182,7 @@ def initial_input_form_generator(subscription_id: UUIDstr) -> FormGenerator:
def netbox_reserve_interfaces(
subscription: Iptrunk, new_node: UUIDstr, new_lag_interface: str, new_lag_member_interfaces: list[dict]
) -> State:
- """Reserve new interfaces in Netbox, only when the new side's router is a NOKIA router."""
+ """Reserve new interfaces in Netbox, only when the new side's router is a Nokia router."""
new_side = Router.from_subscription(new_node).router
nbclient = NetboxClient()
# Create :term:`LAG` interfaces
@@ -739,7 +739,7 @@ def delete_old_config_real(
def update_ipam(subscription: Iptrunk, replace_index: int, new_node: Router, new_lag_interface: str) -> State:
"""Update :term:`IPAM` resources.
- Move the DNS record pointing to the old side of the trunk, to the new side.
+ Move the :term:`DNS` record pointing to the old side of the trunk, to the new side.
"""
v4_addr = subscription.iptrunk.iptrunk_ipv4_network[replace_index]
# IPv6 networks start with an unused address we need to skip past.
diff --git a/gso/workflows/iptrunk/validate_iptrunk.py b/gso/workflows/iptrunk/validate_iptrunk.py
index 47d30dc5..47db6256 100644
--- a/gso/workflows/iptrunk/validate_iptrunk.py
+++ b/gso/workflows/iptrunk/validate_iptrunk.py
@@ -32,7 +32,7 @@ def validate_router_config(subscription: Iptrunk, callback_route: str) -> None:
def verify_ipam_loopback(subscription: Iptrunk) -> None:
"""Validate the :term:`IPAM` resources for the :term:`LAG` interfaces.
- Raises an :class:`orchestrator.utils.errors.ProcessFailureError` if IPAM is configured incorrectly.
+ Raises an :class:`orchestrator.utils.errors.ProcessFailureError` if :term:`IPAM` is configured incorrectly.
"""
ipam_errors = []
ipam_v4_network = infoblox.find_network_by_cidr(subscription.iptrunk.iptrunk_ipv4_network)
@@ -70,7 +70,7 @@ def validate_iptrunk() -> StepList:
"""Validate an existing, active IP Trunk subscription.
* Run an Ansible playbook to verify the configuration is intact.
- * Verify that the LAG interfaces are correctly configured in IPAM.
+ * Verify that the :term:`LAG` interfaces are correctly configured in :term:`IPAM`.
"""
return (
init
diff --git a/gso/workflows/router/create_router.py b/gso/workflows/router/create_router.py
index dfa0b27b..ff859d87 100644
--- a/gso/workflows/router/create_router.py
+++ b/gso/workflows/router/create_router.py
@@ -131,7 +131,7 @@ def ipam_allocate_loopback(subscription: RouterInactive) -> State:
@step("Create NetBox Device")
def create_netbox_device(subscription: RouterInactive) -> State:
- """Create a new NOKIA device in Netbox."""
+ """Create a new Nokia device in Netbox."""
fqdn = subscription.router.router_fqdn
site_tier = subscription.router.router_site.site_tier if subscription.router.router_site else None
if not fqdn or not site_tier:
@@ -147,7 +147,7 @@ def create_netbox_device(subscription: RouterInactive) -> State:
def verify_ipam_loopback(subscription: RouterInactive) -> None:
"""Validate the :term:`IPAM` resources for the loopback interface.
- Raises an :class:`orchestrator.utils.errors.ProcessFailureError` if IPAM is configured incorrectly.
+ Raises an :class:`orchestrator.utils.errors.ProcessFailureError` if :term:`IPAM` is configured incorrectly.
"""
host_record = infoblox.find_host_by_fqdn(f"lo0.{subscription.router.router_fqdn}")
if not host_record or str(subscription.subscription_id) not in host_record.comment:
diff --git a/gso/workflows/router/validate_router.py b/gso/workflows/router/validate_router.py
index f63c9e8a..d768eb37 100644
--- a/gso/workflows/router/validate_router.py
+++ b/gso/workflows/router/validate_router.py
@@ -31,7 +31,7 @@ def validate_router_config(subscription: Router, callback_route: str) -> None:
def verify_ipam_loopback(subscription: Router) -> None:
"""Validate the :term:`IPAM` resources for the loopback interface.
- Raises an :class:`orchestrator.utils.errors.ProcessFailureError` if IPAM is configured incorrectly.
+ Raises an :class:`orchestrator.utils.errors.ProcessFailureError` if :term:`IPAM` is configured incorrectly.
"""
host_record = infoblox.find_host_by_fqdn(f"lo0.{subscription.router.router_fqdn}")
if not host_record or str(subscription.subscription_id) not in host_record.comment:
@@ -48,7 +48,7 @@ def validate_router() -> StepList:
"""Validate an existing, active Router subscription.
* Run an Ansible playbook to verify the configuration is intact.
- * Verify that the loopback interface is correctly configured in IPAM.
+ * Verify that the loopback interface is correctly configured in :term:`IPAM`.
"""
return (
init
--
GitLab