update documentation, update vale rules, reduce warnings and suggestions made by vale

Signed-off-by: Karel van Klink <karel.vanklink@geant.org>

.gitignore

@@ -8,4 +8,5 @@ venv/
 docs/build
 vale/styles/*
 !vale/styles/Vocab/
+!vale/styles/custom/
 public/

.gitlab-ci.yml

@@ -3,16 +3,6 @@ stages:
   - publish-prod-2
   - publish-prod-1
 
-#image: python:latest
-#pages:
-#  stage: deploy
-#  script:
-#    - pip install mkdocs-material
-#    - mkdocs build --site-dir public
-#  artifacts:
-#    paths:
-#      - public
-
 ##### Sphinx  - Generate documentation
 build-documentation:
   stage: documentation

docs/admin_guide/WFO/iptrunks.md

-# IP trunks
-
-IPtrunks are core links between two GÈANT routers.
-IPtrunk is a special service since on the interfaces at the end of the trunk no VLAN multiplexing is allowed.
-For this reason in case of IPtrunk we do not use the canonical decomposition that leverages demarcation point.
-
-## Modelling and attributes
-
-The relevant attributes for an IPTrunk are the following|
-
-| Attribute name | Attribute type | Description |
-| -------------- | -------------- | ----------- |
-| geant_s_sid| String | GÉANT service ID associated with this trunk. |
-|iptrunk_description| str |A human-readable description of this trunk.|
-|iptrunk_type| IptrunkType|The type of trunk, can be either dark fibre or leased capacity.|
-|iptrunk_speed| str | should be of PhyPortCapacity type The speed of the trunk, measured per interface associated with it.|
-|iptrunk_minimum_links| int|The minimum amount of links the trunk should consist of.|
-|iptrunk_isis_metric| int|The IS-IS metric of this link|
-|iptrunk_ipv4_network| IPv4Network|The IPv4 network used for this trunk.|
-|iptrunk_ipv6_network| IPv6Network|The IPv6 network used for this trunk.|
-|iptrunk_sideA_node| DeviceBlock|The router that hosts the A side of the trunk.|
-|iptrunk_sideA_ae_iface| str|The name of the interface on which the trunk connects.|
-|iptrunk_sideA_ae_geant_a_sid| str|The service ID of the interface.|
-|iptrunk_sideA_ae_members| list[str] = Field(default_factory=list)|A list of interface members that make up the aggregated Ethernet interface.|
-|iptrunk_sideA_ae_members_description| list[str] = Field(default_factory=list)|The list of descriptions that describe the list of interface members.|
-|iptrunk_sideB_node| DeviceBlock|The router that hosts the B side of the trunk. It possesses the same attributes as the A-side, including the interfaces and its descriptions.|
-|iptrunk_sideB_ae_iface| str | Same as iptrunk_sideA_ae_iface but for B side|
-|iptrunk_sideB_ae_geant_a_sid| str | Same as iptrunk_sideA_ae_geant_a_sid but for B side |
-|iptrunk_sideB_ae_members| list[str] = Field(default_factory=list) | Same as iptrunk_sideA_ae_members but for B side|
-|iptrunk_sideB_ae_members_description| list[str] = Field(default_factory=list) | Same as iptrunk_sideA_ae_members_description but for B side|
-
-
-## Workflows
-
-### Deployment
-
-This the workflow that brings the subscription from INACTIVE to PROVISIONING and finally to ACTIVE.
-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 contains the subscription_id and the process_id. Included in this there is also 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 again ```iptrunks_checks.yaml```
-
-The trunk is deployed with an initial ISIS metric of 9000 to prevent traffic to pass.
-
-
-### Undeployment
-
-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 wait 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
-
-
-### Modification
-
-To modify IPtrunks we have 2 different workflows:
-- Modify ISIS metric - modifies protocols/isis/interface
-- Modify Trunk interface - modifies lag interfaces and members. This is used to increase capacity or to change SID/Iface descriptions.
-
-In both cases, the strategy is to re-apply the necessary template to the configuration construct: using a "replace" strategy only the necessary modifications will be applied.
-
-At the time of writing, the deletion of members from an existing IPtrunk is not supported.
-
-
-### Migration
-

docs/admin_guide/oss_bss/ipam.md

-# Integration with Infoblox
\ No newline at end of file
+# Integration with Infoblox
+
+TBA

docs/admin_guide/oss_bss/kentik.md

 # Integration with Kentik
 
+TBA

docs/admin_guide/oss_bss/librenms.md

 # Integration with LibreNMS
+
+TBA

docs/admin_guide/oss_bss/netbox.md

-# Integration with Netbox
\ No newline at end of file
+# Integration with Netbox
+
+TBA

docs/admin_guide/wfo/iptrunks.md

+# IP trunks
+
+IP trunks are core links between two GÉANT routers.
+The IP trunk is a special service since on the interfaces at the end of the trunk, no VLAN multiplexing is allowed.
+For this reason, in case of an IP trunk, we do not use the canonical decomposition that leverages a demarcation point.
+
+## Modelling and attributes
+
+The relevant attributes for an IPTrunk are the following:
+
+| Attribute name                      | Attribute type                            | Description                                                                                          |
+|-------------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------------------|
+| geant_s_sid                         | `str`                                     | GÉANT service ID associated with this trunk.                                                         |
+| iptrunk_description                 | `str`                                     | A human-readable description of this trunk.                                                          |
+| iptrunk_type                        | `IptrunkType`                             | The type of trunk, can be either dark fibre or leased capacity.                                      |
+| iptrunk_speed                       | `str`                                     | should be of PhyPortCapacity type The speed of the trunk, measured per interface associated with it. |
+| iptrunk_minimum_links               | `int`                                     | The minimum amount of links the trunk should consist of.                                             |
+| iptrunk_isis_metric                 | `int`                                     | The IS-IS metric of this link                                                                        |
+| iptrunk_ipv4_network                | `IPv4Network`                             | The IPv4 network used for this trunk.                                                                |
+| iptrunk_ipv6_network                | `IPv6Network`                             | The IPv6 network used for this trunk.                                                                |
+| iptrunk_side_node                   | `DeviceBlock`                             | The router that hosts the A side of the trunk.                                                       |
+| iptrunk_side_ae_iface               | `str`                                     | The name of the interface on which the trunk connects.                                               |
+| iptrunk_side_ae_geant_a_sid         | `str`                                     | The service ID of the interface.                                                                     |
+| iptrunk_side_ae_members             | `list[str] = Field(default_factory=list)` | A list of interface members that make up the aggregated Ethernet interface.                          |
+| iptrunk_side_ae_members_description | `list[str] = Field(default_factory=list)` | The list of descriptions that describe the list of interface members.                                |
+
+## Workflows
+
+### Deployment
+
+This the workflow that brings the subscription from INACTIVE to PROVISIONING and finally to ACTIVE.
+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 again `iptrunks_checks.yaml`
+
+The trunk is deployed with an initial ISIS metric of 9000 to prevent traffic to pass.
+
+### Termination
+
+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 wait 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
+
+### Modification
+
+To modify IP Trunks, have 2 different workflows exist:
+
+- Modify ISIS metric - modifies protocols/ISIS/interface
+- Modify Trunk interface - modifies lag interfaces and members. This is used to increase capacity or to change
+SID/interface descriptions.
+
+In both cases, the strategy is to re-apply the necessary template to the configuration construct: using a "replace"
+strategy only the necessary modifications will be applied.
+
+At the time of writing, the deletion of members from an existing IPtrunk is not supported.
+
+### Migration
+
+TBA

docs/admin_guide/WFO/wfo.md → docs/admin_guide/wfo/wfo.md

@@ -4,7 +4,7 @@
 
 ### [Sites](./sites.md)
 ### [Routers](./routers.md)
-### [IPtrunks](./iptrunks.md)
+### [IP trunks](./iptrunks.md)
 
 ## Maintenance
 

docs/architecture/components/ansible/index.md

 # Ansible
 
-Ansible is responsible of:
+Ansible is responsible for:
 
-- compiling, deploying and deleting configuration on targeted devices
-- gather operational information from the targeted devices
+- Compiling, deploying, and deleting configuration on targeted devices
+- Gathering operational information from the targeted devices
 
-The Ansible subsystem is composed by three main functional parts:
-
-- A plugin that is responsible for exposing the Ansible engine to workflow orchestrator via APIs
-- A set of Ansible roles and playbooks that interacts with the network elements
-- A set of global variables stored in a Git repository that partially build the Ansible Inventory
+The Ansible subsystem is composed of three main functional parts:
 
+- A plugin that is responsible for exposing the Ansible engine to the Workflow Orchestrator via APIs
+- A set of Ansible roles and playbooks that interacts with network elements
+- A set of global variables stored in a Git repository that build the Ansible Inventory

docs/architecture/components/index.md

 # Components of GAP
 
-As previously stated, GAP is a platform and not a monolithic piece of software. GAP interacts with different OSS/BSS systems already present in GÉANT and these are tightly part of it in a certain sense.
+As stated before, GAP is a platform and not a monolithic piece of software. GAP interacts with different OSS/BSS
+systems already present in GÉANT and these are tightly integrated with the automation platform.
 
-From a high level point of view, GAP can be seen as the sum of these parts:
+From a high level point of view, GAP can be seen as the sum of the following parts:
 
-- __A service database__ called CoreDB that contains the models of the service instances, called _subscriptions_. Subscriptions are abstract objects that represent functional configuration constructs: the attributes that characterize these objects are defined in the _domain models_.
+- __A service database__ called CoreDB that stores the models of the service instances, called _subscriptions_.
+Subscriptions are abstract objects that represent functional configuration constructs: the attributes that characterize
+these objects are defined in the _domain models_.
 
 - __An orchestration engine__ called Workflow Orchestrator that is capable of executing lists of steps called workflows.
 
 - __A web interface__ for operators, called Orchestrator GUI to intuitively launch and inspect workflows.
 
-- __An automation engine__, Ansible, capable of interacting with network devices to configure them or to gather operational information.
+- __An automation engine__, Ansible, capable of interacting with network devices to configure them or to gather
+operational information.
 
 - __A set of authoritative systems to manage resources__:
     - IP addresses and DNS names (Infoblox)
     - Physical interfaces (Netbox)
 
-  To interact with these external systems, specific plugins or wrappers are in place.
+To interact with these external systems, specific plugins or wrappers are in place.
 
-An overview of how these components interacts is depicted in the following diagram:
+An overview of how these components interact is depicted in the following diagram:
 
-![](../../assets/images/TNC23_diagrams-WFO_GAP.drawio.png){ width=300}
\ No newline at end of file
+![](../../assets/images/TNC23_diagrams-WFO_GAP.drawio.png){ width=300}

docs/architecture/components/netbox/index.md

 # Netbox
 
-Netbox is a DCIM (DataCenter Infrastructure Manager) capable of managing inventory of Sites, Racks, Devices, Ports etc...
+Netbox is a DCIM capable of managing inventory of Sites, Racks, Devices, Ports, etc.
 
-In our case we use Netbox to store information about utilization of physical interfaces.
+GAP makes use of Netbox to store information about which physical interfaces are in use.
 
-There are some strong assumptions that we make:
+There are some strong assumptions that are made about GAP:
 
-- all the nodes have a fixed configuration that does not change often over time
-- the only point where operators can allocate interfaces is GAP.
-- we do not manage the legacy Juniper network
+- All the nodes have fixed configuration that does not change often over time
+- The only point where operators can assign interfaces is GAP
+- The legacy Juniper network is not managed by GAP
 
 ## Network hardware
 
-The new routers have a static hardware configuration which is dependant from the TIER. The following table summarize it:
+The new routers have a static hardware configuration which depends on the tier of the site at which it is installed.
+The following table summarizes the possible configurations:
 
-|Tier|Chassis|Control plane|Switching fabric|Linecard|
-|--|--|--|--|--|
-|Tier1|SR7s|2x CPM2-s|4x SFM7-s|2x XCM2 - 2x XMA2-s (36p QSFPDD)|
-|Tier2|SR7s|2x CPM2-s|4x SFM7-s|2x XCM2 - 2x XMA2-s (36p QSFPDD)|
-|Tier3|TBD|TBD|TBD|TBD|
-|Tier4|TBD|TBD|TBD|TBD|
\ No newline at end of file
+| Tier | Chassis | Control plane | Switching fabric | Linecard                         |
+|------|---------|---------------|------------------|----------------------------------|
+| 1    | SR7s    | 2x CPM2-s     | 4x SFM7-s        | 2x XCM2 - 2x XMA2-s (36p QSFPDD) |
+| 2    | SR7s    | 2x CPM2-s     | 4x SFM7-s        | 2x XCM2 - 2x XMA2-s (36p QSFPDD) |
+| 3    | TBD     | TBD           | TBD              | TBD                              |
+| 4    | TBD     | TBD           | TBD              | TBD                              |

docs/architecture/components/wfo/index.md

 # Workflow Orchestrator
 
-In this page, we describe the mechanisms that govern:
+In this page, a description is given of the mechanisms that govern:
 
 - Workflow Orchestrator
 - CoreDB
-- The "framework" for the integration plugins
\ No newline at end of file
+- The framework for the integration of plugins
+
+(TBA)

docs/architecture/config_decomposition/index.md

@@ -2,54 +2,64 @@
 
 ## Functional decomposition
 
-Every configuration statement express a particular function, we currently decompose the configuration according to this taxonomy:
+Every configuration statement expresses a particular function, this taxonomy decomposes the various types of
+configuration:
 
 ![](../../assets/images/TNC23_diagrams-ConfigSlicing.drawio.png){ width='300' }
 
 ### Base configuration
 
-It is present on all the nodes it performs exactly the same function adapting to particular values or characteristic of the node itself.
+It is present on all nodes, it performs exactly the same functionality, and is adapted to particular values or
+characteristics of the node itself.
+
 Examples are:
 
 - SNMP communities: are the same for all the routers, including the client list
-- AAA (local user and radius authentication): the same on all the routers, but the source address of Radius requests is the loopback of the specific device
+- AAA (local user and radius authentication): the same on all the routers, but the source address of Radius requests is
+the loopback of the specific device
 
-Once the router has been configured with the base configuration, it is ready for the installation of one or more IPtrunks that will connect it to the rest of the network.
+Once the router has been configured with the base configuration, it is ready for the installation of one or more IP
+trunks. Doing so will connect it to the rest of the network.
 
-At this point, the router's loopback is reachable via IGP and the new device can be inserted in the network configuring iBGP mesh and adding it to tooling.
+At this point, the router's loopback is reachable via IGP and the new device can be inserted in the network configuring
+iBGP mesh and adding it to tooling.
 
-Now the router is in service, ready to carry services.
+✨ Now the router is in service, ready to deliver services. ✨
 
 ### Service prerequisites
 
-L3VPNs must exist on the router before customer facing services can be configured, there might be also specific communities or routing policies that are generic and are considered as prerequisite for customer connections.
+L3VPNs must exist on the router before customer facing services can be configured. There might also be specific
+communities or routing policies that are generic and are considered as prerequisite for customer connections.
 This functional block is responsible for this.
 
 
 ### Service
 
-This block represent a service on the edge: a L2circuit or a BGP peer. This block is itself decomposed in other parts, according to the functional parts needed by configuration.
-In general, we use a meta-service called demarcation point, to identify the physical interface on which the service should be delivered:
+This block represents a service on the edge: a L2 circuit or a BGP peer. This block is itself decomposed in other parts,
+according to the functional parts needed by configuration. In general, a meta-service called a demarcation point is
+used to identify the physical interface on which the service should be delivered:
 
 ![](../../assets/images/TNC23_diagrams-Service_stitching.drawio.png){ width='400' }
 
-A service is always delivered on a VLAN (that can be native VLAN in some particular cases, for example IPtrunk). The VLAN is called _Service Delivery Point_.
+A service is always delivered on a VLAN (that can be native VLAN in some particular cases, for example an IP trunk).
+The VLAN is called a _Service Delivery Point_.
 
 ## Separation of data and configuration
 
-Configuration can be seen as the composition of some abstract data structure that represent the business logic, and a template that match the router's specific configuration dialect.
-In the following example we are going to configure DNS servers on a Juniper and a Nokia router:
+Configuration can be seen as the composition of some abstract data structure that represent the business logic, and a
+template that match the router's specific configuration dialect. In the following example DNS servers on a Juniper and
+a Nokia router are configured:
 
 DNS servers (abstract data):
 
-```
+```yaml
 system_name_servers:
   - 192.168.1.1
   - 192.168.1.254
 ```
 
 Junos template:
-```
+```jinja
 system {
   replace: name-server {
   {%- for name_server in system_name_servers %}
@@ -60,5 +70,5 @@ system {
 ```
 Nokia template:
 ```
-
+To be added...
 ```
\ No newline at end of file

docs/architecture/dtap/acceptance.md

-# Acceptance environment
\ No newline at end of file
+# Acceptance environment
+
+TBA

docs/architecture/dtap/index.md

-# DTAP Process
\ No newline at end of file
+# DTAP process
+
+TBA