Weighted pool allocation docs and attribute description (#6518)

* Add docs

* Add attribute description

* add inherited generic

Author: minitriga

.vale/styles/spelling-exceptions.txt

@@ -1,5 +1,6 @@
 agent
 Alibaba
+allocation_weight
 Ansible
 anonymized
 append_git_suffix

backend/infrahub/core/schema/definitions/core/resource_pool.py

@@ -40,7 +40,16 @@
     include_in_menu=False,
     branch=BranchSupportType.AWARE,
     generate_profile=False,
-    attributes=[Attr(name="allocation_weight", label="Weight", kind="Number", optional=True, order_weight=10000)],
+    attributes=[
+        Attr(
+            name="allocation_weight",
+            label="Weight",
+            description="Weight determines allocation priority, resources with higher values are selected first.",
+            kind="Number",
+            optional=True,
+            order_weight=10000,
+        )
+    ],
 )
 
 core_ip_prefix_pool = NodeSchema(

docs/docs/guides/resource-manager.mdx

@@ -524,6 +524,40 @@ Execute this mutation twice, note the identifier. The resulting IP prefix should
 
 :::
 
+:::success Weighted allocation of an IP prefix
+
+When multiple resources are managed by a resource manager and need to be allocated in a specific order, you can assign weights to control that behavior.
+
+To enable this, update your schema to inherit from the `CoreWeightedPoolResource` generic. This adds the `allocation_weight` attribute to your Prefix resource.
+
+Set a value for allocation_weight when creating the Prefix. **Higher values are preferred first during allocation**.
+
+<Tabs>
+  <TabItem value="YAML" label="Schema update">
+
+  ```yaml
+nodes:
+  - name: IPPrefix
+    namespace: Ipam
+    include_in_menu: false
+    inherit_from:
+      - "BuiltinIPPrefix"
+      - "CoreWeightedPoolResource"
+    description: "IPv4 or IPv6 network"
+    label: "IP Prefix"
+    relationships:
+      - name: vlan
+        peer: IpamVLAN
+        optional: true
+        cardinality: one
+        kind: Attribute
+  ```
+
+  </TabItem>
+</Tabs>
+
+:::
+
 ## Using number pool
 
 A `CoreNumberPool` is connected to a node's numeric attribute. It lets you automatically assign numbers from a set range as values for that attribute.

docs/docs/topics/resource-manager.mdx

@@ -17,6 +17,8 @@ A resource manager in Infrahub allocates resources in a branch agnostic way. Whe
 
 Depending on how you use the resource manager, it can allocate resources in an idempotent way. This is helpful when you want to use generators that have to behave in an idempotent way.
 
+Resources that inherit from `CoreWeightedPoolResource` have an `allocation_weight` attribute, which lets you influence allocation order. Resources with higher weights are preferred first when allocating a Prefix or IP Address from a pool.
+
 Resources can be allocated in 2 different ways:
 
 - Direct allocation: A direct allocation is typically used when you don't need the resource to be related to another node in Infrahub, or if you want establish such a relation at a later time. For example, you want to allocated an IP address out of a pool that is not going to be linked to another node in Infrahub.