From bd7b4ec57a9a26230df432e62840dbf43961ac38 Mon Sep 17 00:00:00 2001 From: Iddo Date: Mon, 7 Sep 2026 09:41:08 +0200 Subject: [PATCH 1/3] docs: render optional use case lists on schema reference pages --- .gitignore | 1 + docs/_templates/schema_reference.j2 | 18 ++++++++++++++++++ tasks/docs.py | 3 +++ 3 files changed, 22 insertions(+) diff --git a/.gitignore b/.gitignore index 315f7f6c..d547c4cd 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ __pycache__ # uv .venv/ .python-version +.claude/settings.local.json diff --git a/docs/_templates/schema_reference.j2 b/docs/_templates/schema_reference.j2 index a15ecc85..8e352d75 100644 --- a/docs/_templates/schema_reference.j2 +++ b/docs/_templates/schema_reference.j2 @@ -77,6 +77,24 @@ title: {{ schema.name }} {% if schema.attribution -%} - **Attribution:** {{ schema.attribution }} {% endif %} +{% if schema.use_cases or schema.not_covered %} + +## Use cases +{% if schema.use_cases %} + +This extension covers: +{% for item in schema.use_cases %} +- {{ item }} +{% endfor -%} +{% endif -%} +{% if schema.not_covered %} + +Out of scope, and what to reach for instead: +{% for item in schema.not_covered %} +- {{ item }} +{% endfor -%} +{% endif -%} +{% endif %} {% if schema.nodes %} ## Nodes diff --git a/tasks/docs.py b/tasks/docs.py index a5c987bc..7955688f 100644 --- a/tasks/docs.py +++ b/tasks/docs.py @@ -113,6 +113,9 @@ def _generate_schema_reference_content(schema_key: str, schema_metadata: dict) - "name": schema_metadata.get("name", ""), "description": schema_metadata.get("description", ""), "attribution": schema_metadata.get("attribution", ""), + # Optional. Extensions that omit these render no "Use cases" section at all. + "use_cases": schema_metadata.get("use_cases", []), + "not_covered": schema_metadata.get("not_covered", []), } # Compute link for dependencies From 9973c27aabf851d3d9263c9722cb713f878237e9 Mon Sep 17 00:00:00 2001 From: Iddo Date: Mon, 7 Sep 2026 09:41:44 +0200 Subject: [PATCH 2/3] docs: regenerate reference pages for the current kind names The committed pages still named InfraGenericDevice, InfraIPAddress and InfraPrefix. The schemas renamed those kinds and the generated output was never refreshed, so docs.generate rewrote 15 pages on an untouched tree. This is that refresh, kept separate from any schema change. --- docs/docs/reference/cluster.mdx | 4 +-- docs/docs/reference/compute.mdx | 2 +- docs/docs/reference/dcim.mdx | 6 ++--- docs/docs/reference/device_module.mdx | 14 +++++----- docs/docs/reference/ipam.mdx | 4 +-- docs/docs/reference/lag.mdx | 4 +-- docs/docs/reference/peering_ixp.mdx | 6 ++--- docs/docs/reference/physical_disk.mdx | 2 +- docs/docs/reference/routing_policies_bgp.mdx | 8 +++--- docs/docs/reference/routing_policies_ospf.mdx | 4 +-- docs/docs/reference/routing_policies_pim.mdx | 4 +-- docs/docs/reference/security.mdx | 27 ++++++++++--------- docs/docs/reference/transceiver.mdx | 2 +- docs/docs/reference/vrf.mdx | 8 +++--- docs/docs/reference/vrrp.mdx | 2 +- 15 files changed, 49 insertions(+), 48 deletions(-) diff --git a/docs/docs/reference/cluster.mdx b/docs/docs/reference/cluster.mdx index 63659d3c..a37e12ec 100644 --- a/docs/docs/reference/cluster.mdx +++ b/docs/docs/reference/cluster.mdx @@ -119,8 +119,8 @@ generics: label: Nodes kind: Component cardinality: many - identifier: worker_in_cluster optional: true + identifier: worker_in_cluster order_weight: 1500 extensions: nodes: @@ -128,8 +128,8 @@ extensions: relationships: - name: worker_in_cluster peer: ClusterGenericComputeUnitNodes - kind: Generic label: Worker in cluster + kind: Generic cardinality: one optional: true identifier: worker_in_cluster diff --git a/docs/docs/reference/compute.mdx b/docs/docs/reference/compute.mdx index 3e970fb8..ab0549b0 100644 --- a/docs/docs/reference/compute.mdx +++ b/docs/docs/reference/compute.mdx @@ -130,8 +130,8 @@ nodes: description: A virtual machine hosted on a server or a cluster. label: Virtual Machine icon: carbon:virtual-machine - menu_placement: ComputeGenericUnit include_in_menu: true + menu_placement: ComputeGenericUnit inherit_from: - ComputeGenericUnit - DcimGenericDevice diff --git a/docs/docs/reference/dcim.mdx b/docs/docs/reference/dcim.mdx index fcccd43e..626fe1ac 100644 --- a/docs/docs/reference/dcim.mdx +++ b/docs/docs/reference/dcim.mdx @@ -287,8 +287,8 @@ generics: - name: name kind: Text unique: true - allow_override: any optional: false + allow_override: any order_weight: 1000 - name: position kind: Number @@ -598,8 +598,8 @@ nodes: peer: OrganizationManufacturer kind: Attribute cardinality: one - identifier: manufacturer__platform optional: true + identifier: manufacturer__platform order_weight: 1300 - name: Device namespace: Dcim @@ -693,8 +693,8 @@ nodes: peer: InterfaceHasSubInterface kind: Attribute cardinality: one - identifier: sub__interface optional: true + identifier: sub__interface description: Parent interface to which this sub-interface belongs order_weight: 1600 diff --git a/docs/docs/reference/device_module.mdx b/docs/docs/reference/device_module.mdx index 7d7865bf..f4af389a 100644 --- a/docs/docs/reference/device_module.mdx +++ b/docs/docs/reference/device_module.mdx @@ -153,13 +153,13 @@ generics: kind: Text unique: true read_only: true - optional: false - allow_override: any computed_attribute: kind: Jinja2 jinja2_template: '{{ module_bay__computed_name__value }}' + optional: false description: Name computed from the module bay; concrete module kinds may refine it. + allow_override: any order_weight: 1000 - name: serial_number kind: Text @@ -285,9 +285,9 @@ nodes: order_weight: 1000 - name: position kind: Number - optional: true parameters: min_value: 1 + optional: true description: Numeric position of the bay within the device (e.g. slot 1, 2, 3). order_weight: 1050 - name: description @@ -296,10 +296,6 @@ nodes: order_weight: 1100 - name: role kind: Dropdown - optional: true - description: The role of the module bay, indicating the type of module it is intended - to receive. - order_weight: 1300 choices: - name: supervisor label: Supervisor @@ -317,6 +313,10 @@ nodes: label: Fan description: Bay intended for a fan module. color: '#D2B4DE' + optional: true + description: The role of the module bay, indicating the type of module it is intended + to receive. + order_weight: 1300 relationships: - name: device peer: DcimPhysicalDevice diff --git a/docs/docs/reference/ipam.mdx b/docs/docs/reference/ipam.mdx index c15c8e2e..97b04bbd 100644 --- a/docs/docs/reference/ipam.mdx +++ b/docs/docs/reference/ipam.mdx @@ -89,14 +89,14 @@ version: '1.0' generics: - name: VLANGroupScope namespace: Ipam - label: VLAN Group Scope description: Mixin for objects that can scope a VLAN group (e.g. Region, Site). The reverse relationship is added by extensions/vlan. + label: VLAN Group Scope include_in_menu: false - name: PrefixScope namespace: Ipam - label: Prefix Scope description: Mixin for objects that can scope IP prefixes (e.g. Region, Site). + label: Prefix Scope include_in_menu: false relationships: - name: prefixes diff --git a/docs/docs/reference/lag.mdx b/docs/docs/reference/lag.mdx index dae6d84a..27a40d0a 100644 --- a/docs/docs/reference/lag.mdx +++ b/docs/docs/reference/lag.mdx @@ -95,8 +95,8 @@ generics: label: Member(s) kind: Attribute cardinality: many - identifier: interface__bundle optional: true + identifier: interface__bundle description: Physical Interfaces that are members of this aggregate order_weight: 1800 nodes: @@ -149,9 +149,9 @@ nodes: label: Member(s) kind: Attribute cardinality: many + optional: true identifier: interface__bundle common_parent: device - optional: true description: Physical Interfaces that are members of this aggregate order_weight: 1800 extensions: diff --git a/docs/docs/reference/peering_ixp.mdx b/docs/docs/reference/peering_ixp.mdx index cd5275dc..7635ab5b 100644 --- a/docs/docs/reference/peering_ixp.mdx +++ b/docs/docs/reference/peering_ixp.mdx @@ -254,8 +254,8 @@ nodes: label: IPv6 Address kind: Attribute cardinality: one - identifier: ixpconn__ipv6_address optional: true + identifier: ixpconn__ipv6_address description: IPv6 address assigned to the connection order_weight: 1400 - name: ipv4_address @@ -263,8 +263,8 @@ nodes: label: IPv4 Address kind: Attribute cardinality: one - identifier: ixpconn__ipv4_address optional: true + identifier: ixpconn__ipv4_address description: IPv4 address assigned to the connection order_weight: 1375 - name: internet_exchange_point @@ -288,8 +288,8 @@ nodes: kind: Component cardinality: many optional: true - on_delete: no-action identifier: ixpconn__bgpsessions + on_delete: no-action description: BGP sessions established over this IXP connection order_weight: 1550 - name: tags diff --git a/docs/docs/reference/physical_disk.mdx b/docs/docs/reference/physical_disk.mdx index fdd11d57..3a3cb9f8 100644 --- a/docs/docs/reference/physical_disk.mdx +++ b/docs/docs/reference/physical_disk.mdx @@ -73,8 +73,8 @@ generics: - name: name kind: Text unique: true - allow_override: any optional: false + allow_override: any order_weight: 1000 relationships: - name: physical_disks diff --git a/docs/docs/reference/routing_policies_bgp.mdx b/docs/docs/reference/routing_policies_bgp.mdx index f2c4ee3f..2a5af794 100644 --- a/docs/docs/reference/routing_policies_bgp.mdx +++ b/docs/docs/reference/routing_policies_bgp.mdx @@ -91,8 +91,8 @@ extensions: label: Import Routing Policies kind: Generic cardinality: many - identifier: bgppeergroup__import_policies optional: true + identifier: bgppeergroup__import_policies description: The routing-policies used by this instance for import. order_weight: 1750 - name: export_routing_policies @@ -100,8 +100,8 @@ extensions: label: Export Routing Policies kind: Generic cardinality: many - identifier: bgppeergroup__export_policies optional: true + identifier: bgppeergroup__export_policies description: The routing-policies used by this instance for export. order_weight: 1800 - kind: RoutingBGPSession @@ -118,8 +118,8 @@ extensions: label: Import Routing Policies kind: Generic cardinality: many - identifier: bgpsession__import_policies optional: true + identifier: bgpsession__import_policies description: The routing-policies used by this instance for import. order_weight: 1850 - name: export_routing_policies @@ -127,8 +127,8 @@ extensions: label: Export Routing Policies kind: Generic cardinality: many - identifier: bgpsession__export_policies optional: true + identifier: bgpsession__export_policies description: The routing-policies used by this instance for export. order_weight: 1900 diff --git a/docs/docs/reference/routing_policies_ospf.mdx b/docs/docs/reference/routing_policies_ospf.mdx index 4167c646..9b97fb28 100644 --- a/docs/docs/reference/routing_policies_ospf.mdx +++ b/docs/docs/reference/routing_policies_ospf.mdx @@ -75,8 +75,8 @@ extensions: label: Import Routing Policies kind: Generic cardinality: many - identifier: ospf__import_policies optional: true + identifier: ospf__import_policies description: The routing-policies used by this instance for import. order_weight: 1600 - name: export_routing_policies @@ -84,8 +84,8 @@ extensions: label: Export Routing Policies kind: Generic cardinality: many - identifier: ospf__export_policies optional: true + identifier: ospf__export_policies description: The routing-policies used by this instance for export. order_weight: 1650 diff --git a/docs/docs/reference/routing_policies_pim.mdx b/docs/docs/reference/routing_policies_pim.mdx index 766d59af..63fd1b2f 100644 --- a/docs/docs/reference/routing_policies_pim.mdx +++ b/docs/docs/reference/routing_policies_pim.mdx @@ -75,8 +75,8 @@ extensions: label: Import Routing Policies kind: Generic cardinality: many - identifier: pim__import_policies optional: true + identifier: pim__import_policies description: The routing-policies used by this instance for import. order_weight: 1500 - name: export_routing_policies @@ -84,8 +84,8 @@ extensions: label: Export Routing Policies kind: Generic cardinality: many - identifier: pim__export_policies optional: true + identifier: pim__export_policies description: The routing-policies used by this instance for export. order_weight: 1550 diff --git a/docs/docs/reference/security.mdx b/docs/docs/reference/security.mdx index 8ebd3c9d..77203c7c 100644 --- a/docs/docs/reference/security.mdx +++ b/docs/docs/reference/security.mdx @@ -50,7 +50,7 @@ This schema extension contains models for implementing detailed security. | name | peer | optional | cardinality | kind | | ---- | ---- | -------- | ----------- | ---- | -| ip_address | InfraIPAddress | False | one | Attribute | +| ip_address | IpamIPAddress | False | one | Attribute | ### IPAMIPPrefix @@ -71,7 +71,7 @@ This schema extension contains models for implementing detailed security. | name | peer | optional | cardinality | kind | | ---- | ---- | -------- | ----------- | ---- | -| ip_prefix | InfraPrefix | False | one | Attribute | +| ip_prefix | IpamPrefix | False | one | Attribute | ### IPAddress @@ -272,7 +272,7 @@ This schema extension contains models for implementing detailed security. - **Namespace:** Security - **Icon:** mdi:firewall - **Human Friendly ID:** name__value -- **Inherit From:** InfraGenericDevice, CoreArtifactTarget, SecurityPolicyAssignment +- **Inherit From:** DcimGenericDevice, DcimPhysicalDevice, CoreArtifactTarget, SecurityPolicyAssignment #### Attributes @@ -322,13 +322,13 @@ This schema extension contains models for implementing detailed security. - **Label:** Firewall Interface - **Namespace:** Security - **Icon:** mdi:ethernet -- **Inherit From:** InfraInterface, InfraEndpoint +- **Inherit From:** DcimInterface, DcimEndpoint #### Relationships | name | peer | optional | cardinality | kind | | ---- | ---- | -------- | ----------- | ---- | -| ip_addresses | InfraIPAddress | True | many | Component | +| ip_addresses | IpamIPAddress | True | many | Component | | security_zone | SecurityZone | False | one | Attribute | ## Generics @@ -558,7 +558,7 @@ nodes: optional: true relationships: - name: ip_address - peer: InfraIPAddress + peer: IpamIPAddress cardinality: one kind: Attribute optional: false @@ -579,7 +579,7 @@ nodes: optional: true relationships: - name: ip_prefix - peer: InfraPrefix + peer: IpamPrefix cardinality: one kind: Attribute optional: false @@ -907,14 +907,15 @@ nodes: - name: Firewall namespace: Security inherit_from: - - InfraGenericDevice + - DcimGenericDevice + - DcimPhysicalDevice - CoreArtifactTarget - SecurityPolicyAssignment icon: mdi:firewall include_in_menu: true human_friendly_id: - name__value - menu_placement: InfraGenericDevice + menu_placement: DcimGenericDevice attributes: - name: role kind: Dropdown @@ -1034,16 +1035,16 @@ nodes: - name: FirewallInterface namespace: Security label: Firewall Interface - menu_placement: InfraGenericDevice + menu_placement: DcimGenericDevice include_in_menu: false icon: mdi:ethernet display_label: name__value inherit_from: - - InfraInterface - - InfraEndpoint + - DcimInterface + - DcimEndpoint relationships: - name: ip_addresses - peer: InfraIPAddress + peer: IpamIPAddress optional: true cardinality: many kind: Component diff --git a/docs/docs/reference/transceiver.mdx b/docs/docs/reference/transceiver.mdx index ef002277..2ac312bb 100644 --- a/docs/docs/reference/transceiver.mdx +++ b/docs/docs/reference/transceiver.mdx @@ -297,8 +297,8 @@ extensions: relationships: - name: transceivers peer: DcimGenericTransceiver - kind: Generic label: Transceivers + kind: Generic cardinality: many optional: true order_weight: 1500 diff --git a/docs/docs/reference/vrf.mdx b/docs/docs/reference/vrf.mdx index d09992f7..bf965c7e 100644 --- a/docs/docs/reference/vrf.mdx +++ b/docs/docs/reference/vrf.mdx @@ -111,10 +111,10 @@ nodes: - name: enforce_unique kind: Boolean label: Enforce Unique - description: Declares the intent that prefixes and addresses be unique in this - VRF. Infrahub does not enforce it; use a check or generator. default_value: true optional: true + description: Declares the intent that prefixes and addresses be unique in this + VRF. Infrahub does not enforce it; use a check or generator. order_weight: 1200 - name: description kind: Text @@ -162,16 +162,16 @@ nodes: relationships: - name: import_vrf peer: IpamVRF - kind: Generic label: Imported by VRFs + kind: Generic cardinality: many optional: true identifier: vrf__import order_weight: 1300 - name: export_vrf peer: IpamVRF - kind: Generic label: Exported by VRFs + kind: Generic cardinality: many optional: true identifier: vrf__export diff --git a/docs/docs/reference/vrrp.mdx b/docs/docs/reference/vrrp.mdx index d770996a..90575685 100644 --- a/docs/docs/reference/vrrp.mdx +++ b/docs/docs/reference/vrrp.mdx @@ -134,8 +134,8 @@ nodes: label: VRRP Interfaces kind: Component cardinality: many - on_delete: cascade optional: true + on_delete: cascade order_weight: 1300 - name: VRRPInterface namespace: Network From 8276299956de78ea8e4219aa076f214650b19794 Mon Sep 17 00:00:00 2001 From: Iddo Date: Mon, 7 Sep 2026 20:06:41 +0200 Subject: [PATCH 3/3] chore: drop a comment reference to a directory that never existed objects/extensions/mlag names objects/extensions/dwdm among the files that re-upsert nyc1-rtr01. No such directory exists anywhere in the history. --- objects/extensions/mlag/mlag.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/objects/extensions/mlag/mlag.yml b/objects/extensions/mlag/mlag.yml index 99857226..e98fd2c1 100644 --- a/objects/extensions/mlag/mlag.yml +++ b/objects/extensions/mlag/mlag.yml @@ -25,7 +25,7 @@ # So a fixture that owns a relationship owns its endpoints too. This file # creates, and is the only file anywhere under objects/ that ever saves, # nyc1-rtr02 and nyc1-rtr03. It deliberately does not build the domain on -# nyc1-rtr01: objects/extensions/rack, device_psu_module, dwdm, routing_ospf +# nyc1-rtr01: objects/extensions/rack, device_psu_module, routing_ospf # and routing_pim all re-upsert that device after this file has run. # objects/extensions/routing_bgp and peering_ixp only reference nyc1-rtr02 by # human_friendly_id, which does not save it and so is safe.