add documentation for node seta and update changelog

docs/source/node_sets.rst

@@ -0,0 +1,115 @@
+.. only:: comment
+
+    © Crown-owned copyright 2024, Defence Science and Technology Laboratory UK
+
+.. _network_node_adder:
+
+Network Node Adder Module
+#########################
+
+This module provides a framework for adding nodes to a network in a standardised way. It defines a base class ``NetworkNodeAdder``, which can be extended to create specific node adders, and utility functions to calculate network infrastructure requirements.
+
+The module allows you to use the pre-defined node adders, ``OfficeLANAdder``, or create custom ones by extending the base class.
+
+How It Works
+============
+
+The main class in the module is ``NetworkNodeAdder``, which defines the interface for adding nodes to a network. Child classes are expected to:
+
+1. Define a ``ConfigSchema`` nested class to define configuration options.
+2. Implement the ``add_nodes_to_net(config, network)`` method, which adds the nodes to the network according to the configuration object.
+
+The ``NetworkNodeAdder`` base class handles node adders defined in the primAITE config YAML file as well. It does this by keeping a registry of node adder classes, and uses the ``type`` field of the config to select the appropriate class to which to pass the configuration.
+
+Example Usage
+=============
+
+Via Python API
+--------------
+
+Adding nodes to a network can be done using the python API by constructing the relevant ``ConfigSchema`` object like this:
+
+.. code-block:: python
+
+    net = Network()
+
+    office_lan_config = OfficeLANAdder.ConfigSchema(
+        lan_name="CORP-LAN",
+        subnet_base=2,
+        pcs_ip_block_start=10,
+        num_pcs=8,
+        include_router=False,
+        bandwidth=150,
+    )
+    OfficeLANAdder.add_nodes_to_net(config=office_lan_config, network=net)
+
+In this example, a network with 8 computers connected by a switch will be added to the network object.
+
+
+Via YAML Config
+---------------
+
+.. code-block:: yaml
+    simulation:
+      network:
+        nodes:
+          # ... nodes go here
+        node_sets:
+          - type: office_lan
+            lan_name: CORP_LAN
+            subnet_base: 2
+            pcs_ip_block_start: 10
+            num_pcs: 8
+            include_router: False
+            bandwidth: 150
+          # ... additional node sets can be added below
+
+``NetworkNodeAdder`` reads the ``type`` property of the config, then constructs and passes the configuration to ``OfficeLANAdder.add_nodes_to_net()``.
+
+In this example, a network with 8 computers connected by a switch will be added to the network object. Equivalent to the above.
+
+
+Creating Custom Node Adders
+===========================
+To create a custom node adder, subclass NetworkNodeAdder and define:
+
+* A ConfigSchema class that defines the configuration schema for the node adder.
+* The add_nodes_to_net method that implements how nodes should be added to the network.
+
+Example: DataCenterAdder
+------------------------
+Here is an example of creating a custom node adder, DataCenterAdder:
+
+.. code-block:: python
+
+    class DataCenterAdder(NetworkNodeAdder, identifier="data_center"):
+        class ConfigSchema(NetworkNodeAdder.ConfigSchema):
+            type: Literal["data_center"] = "data_center"
+            num_servers: int
+            data_center_name: str
+
+        @classmethod
+        def add_nodes_to_net(cls, config: ConfigSchema, network: Network) -> None:
+            for i in range(config.num_servers):
+                server = Computer(
+                    hostname=f"server_{i}_{config.data_center_name}",
+                    ip_address=f"192.168.100.{i + 1}",
+                    subnet_mask="255.255.255.0",
+                    default_gateway="192.168.100.1",
+                    start_up_duration=0
+                )
+                server.power_on()
+                network.add_node(server)
+
+**Using the Custom Node Adder:**
+
+.. code-block:: python
+
+    config = {
+        "type": "data_center",
+        "num_servers": 5,
+        "data_center_name": "dc1"
+    }
+
+    network = Network()
+    DataCenterAdder.from_config(config, network)