From 49e709897ed16f2abf40e37d62464017dc2ce082 Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Thu, 25 May 2023 16:34:27 +0100
Subject: [PATCH] Update documentation of ip trunks

---
 build-docs.sh          |  1 +
 docs/source/conf.py    |  2 +-
 lso/routes/device.py   |  2 +-
 lso/routes/ip_trunk.py | 40 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/build-docs.sh b/build-docs.sh
index 796180f..6c37858 100755
--- a/build-docs.sh
+++ b/build-docs.sh
@@ -1,5 +1,6 @@
 python docs/dump-openapi-spec.py
 
+rm -r ./docs/build/*
 sphinx-apidoc lso lso/app.py -o docs/source -d 2 -f
 vale --config=docs/vale/.vale.ini sync
 vale --config=docs/vale/.vale.ini docs/source/*.rst lso/*.py
diff --git a/docs/source/conf.py b/docs/source/conf.py
index b499e94..7b09c5e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -48,7 +48,7 @@ def setup(app):
 
 # -- Project information -----------------------------------------------------
 
-project = 'Lightweight Ansible Runner Provisioner'
+project = 'Lightweight Service Orchestrator'
 copyright = '2023, GÉANT'
 author = 'GÉANT Orchestration & Automation Team'
 
diff --git a/lso/routes/device.py b/lso/routes/device.py
index f97766f..a7bda43 100644
--- a/lso/routes/device.py
+++ b/lso/routes/device.py
@@ -45,7 +45,7 @@ async def provision_node(params: NodeProvisioningParams) \
     :param params: Parameters for provisioning a new node
     :type params: :class:`NodeProvisioningParams`
     :return: Response from the Ansible runner, including a run ID.
-    :rtype: :class:`PlaybookLaunchResponse`
+    :rtype: :class:`lso.playbook.PlaybookLaunchResponse`
     """
     extra_vars = {
         'wfo_device_json': params.subscription,
diff --git a/lso/routes/ip_trunk.py b/lso/routes/ip_trunk.py
index b24c73f..bab6cf6 100644
--- a/lso/routes/ip_trunk.py
+++ b/lso/routes/ip_trunk.py
@@ -16,30 +16,47 @@ config_params = config.load()
 
 class IPTrunkParams(BaseModel):
     """Default parameters for an IPtrunk deployment."""
+    #: The address where LSO should call back to upon completion.
     callback: HttpUrl
+    #: A dictionary representation of the IP trunk
+    #: subscription that is to be provisioned.
     subscription: dict
 
 
 class IPTrunkProvisioningParams(IPTrunkParams):
     """Additional parameters for provisioning an IPtrunk."""
+    #: Whether this playbook execution should be a dry run, or run for real.
+    #: defaults to ``True`` for obvious reasons, also making it an optional
+    #: parameter.
     dry_run: Optional[bool] = True
+    #: The type of object that is changed.
     object: str
 
 
 class IPTrunkModifyParams(IPTrunkParams):
     """Additional parameters for modifying an IPtrunk."""
+    #: Whether this playbook execution should be a dry run, or run for real.
+    #: defaults to ``True`` for obvious reasons, also making it an optional
+    #: parameter.
     dry_run: Optional[bool] = True
+    #: The old subscription object, represented as a dictionary. This allows
+    #: for calculating the difference in subscriptions.
     old_subscription: dict
+    #: The type of object that is changed.
     object: str
 
 
 class IPTrunkCheckParams(IPTrunkParams):
     """Additional parameters for checking an IPtrunk."""
+    #: The name of the check that is to be performed.
     check_name: str
 
 
 class IPTrunkDeleteParams(IPTrunkParams):
     """Additional parameters for deleting an IPtrunk."""
+    #: Whether this playbook execution should be a dry run, or run for real.
+    #: defaults to ``True`` for obvious reasons, also making it an optional
+    #: parameter.
     dry_run: Optional[bool] = True
 
 
@@ -49,6 +66,12 @@ def provision_ip_trunk(params: IPTrunkProvisioningParams) \
     """
     Launch a playbook to provision a new IP trunk service.
     The response will contain either a job ID, or error information.
+
+    :param params: The parameters that define the new subscription object that
+        is to be deployed.
+    :type params: :class:`IPTrunkProvisioningParams`
+    :return: Response from the Ansible runner, including a run ID.
+    :rtype: :class:`lso.playbook.PlaybookLaunchResponse`
     """
     extra_vars = {
         'wfo_trunk_json': params.subscription,
@@ -77,6 +100,11 @@ def provision_ip_trunk(params: IPTrunkProvisioningParams) \
 def modify_ip_trunk(params: IPTrunkModifyParams) -> PlaybookLaunchResponse:
     """
     Launch a playbook that modifies an existing IP trunk service.
+
+    :param params: The parameters that define the change in configuration.
+    :type params: :class:`IPTrunkModifyParams`
+    :return: Response from the Ansible runner, including a run ID.
+    :rtype: :class:`lso.playbook.PlaybookLaunchResponse`
     """
     extra_vars = {
         'wfo_trunk_json': params.subscription,
@@ -106,6 +134,12 @@ def modify_ip_trunk(params: IPTrunkModifyParams) -> PlaybookLaunchResponse:
 def delete_ip_trunk(params: IPTrunkDeleteParams) -> PlaybookLaunchResponse:
     """
     Launch a playbook that deletes an existing IP trunk service.
+
+    :param params: Parameters that define the subscription that should get
+        terminated.
+    :type params: :class:`IPTrunkDeleteParams`
+    :return: Response from the Ansible runner, including a run ID.
+    :rtype: :class:`lso.playbook.PlaybookLaunchResponse`
     """
     extra_vars = {
         'wfo_trunk_json': params.subscription,
@@ -134,6 +168,12 @@ def delete_ip_trunk(params: IPTrunkDeleteParams) -> PlaybookLaunchResponse:
 def check_ip_trunk(params: IPTrunkCheckParams) -> PlaybookLaunchResponse:
     """
     Launch a playbook that performs a check on an IP trunk service instance.
+
+    :param params: Parameters that define the check that is going to be
+        executed, including on which relevant subscription.
+    :type params: :class:`IPTrunkCheckParams`
+    :return: Response from the Ansible runner, including a run ID.
+    :rtype: :class:`lso.playbook.PlaybookLaunchResponse`
     """
     extra_vars = {
         'wfo_ip_trunk_json': params.subscription,
-- 
GitLab