Move workflow docstrings into Python files

gso/workflows/iptrunk/activate_iptrunk.py

-"""Activate IP trunk takes a provisioning trunk to the active lifecycle state."""
+"""Activate IP trunk takes a provisioning trunk to the active lifecycle state.
+
+When the SharePoint checklist of a trunk is completed, this workflow is run to take the subscription from `PROVISIONING`
+to `ACTIVE`. The operator is asked to give a URL to the completed checklist.
+"""
 
 from orchestrator.config.assignee import Assignee
 from orchestrator.forms import FormPage

gso/workflows/iptrunk/create_iptrunk.py

-"""A creation workflow that deploys a new IP trunk service."""
+"""A creation workflow that deploys a new IP trunk service.
+
+This the workflow that brings the subscription from `INACTIVE` to `PROVISIONING`. The deployment of a new IPtrunk
+consist in the following steps:
+
+- Fill the form with the necessary fields:
+    - SID
+    - Type
+    - Speed
+    - Nodes
+    - LAG interfaces with description
+    - LAG members with description
+- WFO will query IPAM to retrieve the IPv4/IPv6 Networks necessary for the trunk. The container to use is specified in
+`oss-params.json`
+- The configuration necessary to deploy the LAG is generated and applied to the destination nodes using the Ansible
+playbook `iptrunks.yaml` This is done first in a dry mode (without committing) and then in a real mode committing the
+configuration. The commit message has the `subscription_id` and the `process_id`. Included in this, is the configuration
+necessary to enable LLDP on the physical interfaces.
+- Once the LAG interface is deployed, another Ansible playbook is called to verify that IP traffic can actually flow
+over the trunk ( `iptrunk_checks.yaml`)
+- Once the check is passed, the ISIS configuration will take place using the same `iptrunks.yaml`. Also in this case
+first there is a dry run and then a commit.
+- After this step the ISIS adjacency gets checked using `iptrunks_checks.yaml`
+
+The trunk is deployed with an initial ISIS metric of 90.000 to prevent traffic to pass.
+"""
 
 import json
 from ipaddress import IPv4Address, IPv4Network, IPv6Address, IPv6Network

gso/workflows/iptrunk/deploy_twamp.py

-"""Workflow for adding :term:`TWAMP` to an existing IP trunk."""
+"""Workflow for adding :term:`TWAMP` to an existing IP trunk.
+
+Takes a trunk that is either `PROVISIONING` or `ACTIVE` and deploy configuration for TWAMP. The trunk will not change
+state after running this workflow.
+"""
 
 import json
 

gso/workflows/iptrunk/migrate_iptrunk.py

@@ -2,6 +2,8 @@
 
 For a trunk that originally connected endpoints A and B, this workflow introduces a new endpoint C. The trunk is then
 configured to run from A to C. B is then no longer associated with this IP trunk.
+
+In the input form, the operator selects a new router where this trunk should terminate on.
 """
 
 import copy

gso/workflows/iptrunk/modify_isis_metric.py

-"""A modification workflow for setting a new :term:`ISIS` metric for an IP trunk."""
+"""A modification workflow for setting a new :term:`ISIS` metric for an IP trunk.
+
+The strategy is to re-apply the necessary template to the configuration construct: using a "replace" strategy only the
+necessary modifications will be applied.
+"""
 
 import json
 

gso/workflows/iptrunk/modify_trunk_interface.py

-"""A modification workflow that updates the :term:`LAG` interfaces that are part of an existing IP trunk."""
+"""A modification workflow that updates the :term:`LAG` interfaces that are part of an existing IP trunk.
+
+Modifies LAG interfaces and members. This is used to  increase capacity or to change SID/interface descriptions.
+
+The strategy is to re-apply the necessary template to the configuration construct: using a "replace" strategy only the
+necessary modifications will be applied.
+"""
 
 import json
 from typing import Annotated

gso/workflows/iptrunk/terminate_iptrunk.py

-"""A termination workflow for an active IP trunk."""
+"""A termination workflow for an active IP trunk.
+
+This workflow deletes all the configuration related with an IPtrunk from the network and brings the subscription from
+`ACTIVE` to `TERMINATED`. The steps are the following:
+
+- Modify the ISIS metric of the trunks so to evacuate traffic - and await confirmation from an operator.
+- Delete all the configuration (first dry then actual deletion):
+    - LAG and members of the LAG
+    - reference in LLDP protocol (if Juniper)
+    - reference in ISIS protocol
+- Delete the IPv4/IPv6 networks from IPAM
+"""
 
 import ipaddress
 import json

gso/workflows/router/activate_router.py

-"""Activate router takes a provisioning router to the active lifecycle state."""
+"""Activate router takes a provisioning router to the active lifecycle state.
+
+When the SharePoint checklist of a router is completed, this workflow is run to take the subscription from
+`PROVISIONING` to `ACTIVE`. The operator is asked to give a URL to the completed checklist.
+"""
 
 from orchestrator.config.assignee import Assignee
 from orchestrator.forms import FormPage

gso/workflows/router/create_router.py

-"""A creation workflow for adding a new router to the network."""
+"""A creation workflow for adding a new router to the network.
+
+To add a new router to the GÉANT network, the `create_router` workflow must be executed first. The intake form for this
+workflow requires the following fields to be filled in:
+
+* Trouble ticket number
+* Router vendor
+* Router site
+* Hostname
+* Terminal server port
+* Router role
+
+The hostname is validated, by checking that the resulting FQDN is not already taken in IPAM.
+
+!!! warning
+    The validation only checks whether the FQDN is already taken in IPAM, **not** whether it is registered somewhere on
+    the internet.
+
+When the workflow is started, a subscription object is first instantiated in the service database, containing all the
+information that was provided in the input form at the beginning. Then, the loopback addresses are allocated in IPAM,
+which results in both the IPv4 and IPv6 addresses in the product model.
+
+Once allocated, the first dry run of deploying router configuration takes place. An Ansible playbook is run, with all
+the attributes of the new router. This is where GSO communicates with LSO, and the router configuration is checked, but
+not committed to the machine.
+
+After the dry run, the operator is presented with a view of the outcome of this playbook. This is their opportunity to
+verify successful execution of the Ansible playbook, and whether the difference in configuration is as expected. If not,
+this is their chance to abort the workflow, and no harm is done to the router.
+
+When the operator confirms the outcome of this playbook execution, the playbook runs once again, but it will also commit
+the configuration after checking. With the new router configured, the IPAM resources are verified to ensure this
+external system is configured correctly.
+
+If the new router is a Nokia, all its interfaces are added to Netbox. This is done to keep track of interface
+reservations and bookkeeping. For Juniper routers, this does not need to take place. These existing devices are not
+migrated into Netbox.
+
+Finally, an Ansible playbook is run to verify that the connectivity and optical power levels of the router are in order.
+Once this is completed, a checklist item is created in SharePoint and the router is taken into the `PROVISIONING` state.
+"""
 
 from typing import Self
 

gso/workflows/router/modify_connection_strategy.py

-"""Modify connection strategy workflow. Flipping the connection between in-band to out-of-band."""
+"""Modify connection strategy workflow.
+
+Run this workflow to change the way Ansible playbooks connect to a router. Either via OOB access, or directly to the
+loopback interface.
+"""
 
 from orchestrator.forms import FormPage
 from orchestrator.targets import Target

gso/workflows/router/modify_kentik_license.py

-"""A workflow that modifies the Kentik license of a router."""
+"""A workflow that modifies the Kentik license of a router.
+
+Change the license of a router in Kentik. The operator can select the license from a list of all available plans in
+Kentik, and it will show the utilisation of each license.
+"""
 
 import logging
 from typing import Any

gso/workflows/router/redeploy_base_config.py

-"""A workflow that re-deploys base config on a router."""
+"""A workflow that re-deploys base config on a router.
+
+When a new router is deployed, it is loaded with the current version of configuration that contain the bare necessities.
+For various reasons, this template may change, and the resulting configuration follows from this. To update a router
+'in the wild' where this change should be reflected, the workflow `redeploy_base_config` is used.
+
+This workflow only takes a trouble ticket number as initial input, and deploys the base configuration, first as a dry
+run. After confirmation by an operator, the configuration is committed to the machine, and this completes the workflow.
+"""
 
 from orchestrator.forms import FormPage
 from orchestrator.forms.validators import Label

gso/workflows/router/terminate_router.py

-"""A workflow that terminates a router."""
+"""A workflow that terminates a router.
+
+To terminate a router, the workflow `terminate_router` is used. The operator is presented with an input form that
+requires once again a trouble ticket number. On top of this, there is also the option whether this workflow should
+remove all configuration on the router, and whether IPAM entries related to this device should be removed.
+
+The workflow consists of the following steps:
+
+- Deprovision IPAM resources (if selected).
+- Try to remove configuration form the router (if selected).
+- Commit removal of configuration (if selected).
+- For Nokia devices: remove interfaces from Netbox.
+- Remove the device from LibreNMS.
+- For PE routers: apply the archiving license in Kentik.
+- Set the subscription status to `TERMINATED`.
+"""
 
 import ipaddress
 import json

gso/workflows/router/update_ibgp_mesh.py

-"""Update iBGP mesh workflow. Adds a new P router to the mesh of PE routers in the network."""
+"""Update iBGP mesh workflow. Adds a new P router to the mesh of PE routers in the network.
+
+Once a new router is added to the network, it must become reachable by all other devices. To achieve this, the
+`update_ibgp_mesh` workflow must be executed. This workflow will add the new P router to all PE routers in the network,
+and add all existing PE routers to the new P router. The only input this workflow takes, is a trouble ticket number.
+All other required information is already in the service database.
+
+The workflow will run 5 Ansible playbooks:
+
+1. Check: add P router to all PE routers
+2. Deploy: add P router to all PE routers
+3. Check: add all PE routers to P router
+4. Deploy: add all PE routers to P router
+5. Verify: check that the iBGP has come up
+
+Once these playbooks have been run successfully, the new P router is added to LibreNMS. Finally, the subscription model
+of the router is updated such that `router_access_via_ts` is set to `False`. This is because the router is now reachable
+by other machines by its loopback address. Using out of band access is therefore not needed anymore.
+"""
 
 from typing import Any
 

gso/workflows/site/create_site.py

-"""A creation workflow for adding a new site to the service database."""
+"""A creation workflow for adding a new site to the service database.
+
+The `create_site` workflow creates a new site object in the service database, and sets the subscription lifecycle to
+`ACTIVE`. The attributes that are input using the intake form of the workflow are stored, and nothing else happens.
+"""
 
 from orchestrator.forms import FormPage
 from orchestrator.targets import Target

gso/workflows/site/modify_site.py

-"""A modification workflow for a site."""
+"""A modification workflow for a site.
+
+Attributes of an existing site can be modified using the `modify_site` workflow.
+As a result, other subscriptions that rely on this site will have referenced
+attributes updated as well.
+
+!!! warning
+
+    Be aware that although this *does* update attributes in the services
+    database, it does **not** update any active subscription instances that are
+    already deployed. You will need to run additional workflows to update
+    subscriptions that depend on this change
+"""
 
 from functools import partial
 from typing import Annotated

gso/workflows/site/terminate_site.py

-"""A workflow for terminating a site subscription."""
+"""A workflow for terminating a site subscription.
+
+The `terminate_site` workflow will take an existing and active site subscription from an `ACTIVE` to a `TERMINATED`
+state. This requires all dependant subscription instances to already be terminated. If this is not the case, the
+workflow will be unavailable for an operator to run, accompanied by an error message explaining this fact.
+"""
 
 from orchestrator.forms import FormPage
 from orchestrator.forms.validators import Label