chore: entity docs (#62)

Code examples include all known entities as generated directly from NetBox

Author: paulstuart

README.md

@@ -117,7 +117,7 @@ func main() {
 }
 ```
 
-See all [examples](./examples/main.go) for reference.
+See all [entities examples](./docs/README.md).
 
 ### Using Metadata
 
@@ -665,95 +665,6 @@ repeat `-file` to specify multiple files. OAuth2
 credentials can be supplied using `-client-id` and `-client-secret` or the
 `DIODE_CLIENT_ID` and `DIODE_CLIENT_SECRET` environment variables.
 
-## Supported entities (object types)
-
-* ASN
-* ASN Range
-* Aggregate
-* Circuit
-* Circuit Group
-* Circuit Group Assignment
-* Circuit Termination
-* Circuit Type
-* Cluster
-* Cluster Group
-* Cluster Type
-* Console Port
-* Console Server Port
-* Contact
-* Contact Assignment
-* Contact Group
-* Contact Role
-* Device
-* Device Bay
-* Device Role
-* Device Type
-* FHRP Group
-* FHRP Group Assignment
-* Front Port
-* IKE Policy
-* IKE Proposal
-* IP Address
-* IP Range
-* IP Sec Policy
-* IP Sec Profile
-* IP Sec Proposal
-* Interface
-* Inventory Item
-* Inventory Item Role
-* L2VPN
-* L2VPN Termination
-* Location
-* MAC Address
-* Manufacturer
-* Module
-* Module Bay
-* Module Type
-* Owner
-* Owner Group
-* Platform
-* Power Feed
-* Power Outlet
-* Power Panel
-* Power Port
-* Prefix
-* Provider
-* Provider Account
-* Provider Network
-* RIR
-* Rack
-* Rack Role
-* Rack Type
-* Rear Port
-* Region
-* Role
-* Route Target
-* Service
-* Site
-* Site Group
-* Tag
-* Tenant
-* Tenant Group
-* Tunnel
-* Tunnel Group
-* Tunnel Termination
-* VLAN
-* VLAN Group
-* VLAN Translation Policy
-* VLAN Translation Rule
-* VM Interface
-* VRF
-* Virtual Chassis
-* Virtual Circuit
-* Virtual Circuit Termination
-* Virtual Circuit Type
-* Virtual Device Context
-* Virtual Disk
-* Virtual Machine
-* Wireless Lan
-* Wireless Lan Group
-* Wireless Link
-
 #### Linting
 
 ```shell

docs/README.md

@@ -0,0 +1,169 @@
+# Diode Go SDK - Entity Examples
+
+Source: NetBox v4.5.0
+Generated: 2026-02-13 17:55:35Z
+
+## Prerequisites
+
+- Go 1.25 or later
+- Diode SDK for Go
+
+## Installation
+
+```bash
+go get github.com/netboxlabs/diode-sdk-go@latest
+```
+
+## Configuration
+
+Each example uses constants for configuration. You can modify these in the example code:
+
+```go
+target     = "grpc://localhost:8080/diode"
+appName    = "example-app"
+appVersion = "1.0.0"
+```
+
+## Quick Start
+
+Each entity example is in its own directory with a complete Go module. To run an example:
+
+```bash
+cd examples/device
+go run main.go
+```
+
+## Example Patterns
+
+Each example includes three patterns:
+
+- **Minimal**: Only required fields
+- **Extended**: Required fields plus common optional fields
+- **Explicit**: Fully nested objects with all common fields
+
+Switch between patterns by uncommenting the desired function call in `main()`.
+
+## Available Entity Examples
+
+### Circuits
+
+- [Circuit](examples/circuit/)
+- [CircuitGroup](examples/circuit_group/)
+- [CircuitGroupAssignment](examples/circuit_group_assignment/)
+- [CircuitTermination](examples/circuit_termination/)
+- [CircuitType](examples/circuit_type/)
+- [Provider](examples/provider/)
+- [ProviderAccount](examples/provider_account/)
+- [ProviderNetwork](examples/provider_network/)
+- [VirtualCircuit](examples/virtual_circuit/)
+- [VirtualCircuitTermination](examples/virtual_circuit_termination/)
+- [VirtualCircuitType](examples/virtual_circuit_type/)
+
+### DCIM
+
+- [Cable](examples/cable/)
+- [CablePath](examples/cable_path/)
+- [CableTermination](examples/cable_termination/)
+- [ConsolePort](examples/console_port/)
+- [ConsoleServerPort](examples/console_server_port/)
+- [Device](examples/device/)
+- [DeviceBay](examples/device_bay/)
+- [DeviceRole](examples/device_role/)
+- [DeviceType](examples/device_type/)
+- [FrontPort](examples/front_port/)
+- [Interface](examples/interface_entity/)
+- [InventoryItem](examples/inventory_item/)
+- [InventoryItemRole](examples/inventory_item_role/)
+- [Location](examples/location/)
+- [Manufacturer](examples/manufacturer/)
+- [Module](examples/module/)
+- [ModuleBay](examples/module_bay/)
+- [ModuleType](examples/module_type/)
+- [ModuleTypeProfile](examples/module_type_profile/)
+- [Platform](examples/platform/)
+- [PowerFeed](examples/power_feed/)
+- [PowerOutlet](examples/power_outlet/)
+- [PowerPanel](examples/power_panel/)
+- [PowerPort](examples/power_port/)
+- [Rack](examples/rack/)
+- [RackReservation](examples/rack_reservation/)
+- [RackRole](examples/rack_role/)
+- [RackType](examples/rack_type/)
+- [RearPort](examples/rear_port/)
+- [Region](examples/region/)
+- [Site](examples/site/)
+- [SiteGroup](examples/site_group/)
+- [VirtualChassis](examples/virtual_chassis/)
+- [VirtualDeviceContext](examples/virtual_device_context/)
+
+### Extras
+
+- [CustomField](examples/custom_field/)
+- [CustomFieldChoiceSet](examples/custom_field_choice_set/)
+- [CustomLink](examples/custom_link/)
+- [JournalEntry](examples/journal_entry/)
+- [Tag](examples/tag/)
+
+### IPAM
+
+- [ASN](examples/asn/)
+- [ASNRange](examples/asn_range/)
+- [Aggregate](examples/aggregate/)
+- [FHRPGroup](examples/fhrp_group/)
+- [FHRPGroupAssignment](examples/fhrp_group_assignment/)
+- [IPAddress](examples/ip_address/)
+- [IPRange](examples/ip_range/)
+- [MACAddress](examples/mac_address/)
+- [Prefix](examples/prefix/)
+- [RIR](examples/rir/)
+- [Role](examples/role/)
+- [RouteTarget](examples/route_target/)
+- [Service](examples/service/)
+- [VLAN](examples/vlan/)
+- [VLANGroup](examples/vlan_group/)
+- [VLANTranslationPolicy](examples/vlan_translation_policy/)
+- [VLANTranslationRule](examples/vlan_translation_rule/)
+- [VRF](examples/vrf/)
+
+### Other
+
+- [DeviceConfig](examples/device_config/)
+
+### Tenancy
+
+- [Contact](examples/contact/)
+- [ContactAssignment](examples/contact_assignment/)
+- [ContactGroup](examples/contact_group/)
+- [ContactRole](examples/contact_role/)
+- [Owner](examples/owner/)
+- [OwnerGroup](examples/owner_group/)
+- [Tenant](examples/tenant/)
+- [TenantGroup](examples/tenant_group/)
+
+### VPN
+
+- [IKEPolicy](examples/ike_policy/)
+- [IKEProposal](examples/ike_proposal/)
+- [IPSecPolicy](examples/ip_sec_policy/)
+- [IPSecProfile](examples/ip_sec_profile/)
+- [IPSecProposal](examples/ip_sec_proposal/)
+- [L2VPN](examples/l2vpn/)
+- [L2VPNTermination](examples/l2vpn_termination/)
+- [Tunnel](examples/tunnel/)
+- [TunnelGroup](examples/tunnel_group/)
+- [TunnelTermination](examples/tunnel_termination/)
+
+### Virtualization
+
+- [Cluster](examples/cluster/)
+- [ClusterGroup](examples/cluster_group/)
+- [ClusterType](examples/cluster_type/)
+- [VMInterface](examples/vm_interface/)
+- [VirtualDisk](examples/virtual_disk/)
+- [VirtualMachine](examples/virtual_machine/)
+
+### Wireless
+
+- [WirelessLAN](examples/wireless_lan/)
+- [WirelessLANGroup](examples/wireless_lan_group/)
+- [WirelessLink](examples/wireless_link/)

docs/examples/aggregate/go.mod

@@ -0,0 +1,9 @@
+module aggregate
+
+go 1.25
+
+require github.com/netboxlabs/diode-sdk-go
+
+// Use local SDK for development and validation
+// When copying this example, remove the replace directive and update the require version above
+replace github.com/netboxlabs/diode-sdk-go => ../../..

docs/examples/aggregate/main.go

@@ -0,0 +1,99 @@
+// Package main demonstrates ingesting Aggregate entities using the Diode SDK.
+// This example includes three patterns: Minimal, Extended, and Explicit.
+package main
+
+import (
+	"context"
+	"log"
+
+	"github.com/netboxlabs/diode-sdk-go/diode"
+)
+
+const (
+	target     = "grpc://localhost:8080/diode"
+	appName    = "aggregate-example"
+	appVersion = "1.0.0"
+)
+
+func main() {
+	client, err := diode.NewClient(
+		target,
+		appName,
+		appVersion,
+	)
+	if err != nil {
+		log.Fatalf("Failed to create client: %v", err)
+	}
+
+	// Choose one of the three patterns by uncommenting:
+	aggregate := AggregateMinimal()
+	// aggregate := AggregateExtended()
+	// aggregate := AggregateExplicit()
+
+	resp, err := client.Ingest(context.Background(), []diode.Entity{aggregate})
+	if err != nil {
+		log.Fatalf("Ingestion failed: %v", err)
+	}
+	if resp.Errors != nil {
+		log.Printf("Errors: %v", resp.Errors)
+	} else {
+		log.Println("Aggregate ingested successfully")
+	}
+}
+
+// AggregateMinimal Creates a Aggregate with only required fields.
+func AggregateMinimal() *diode.Aggregate {
+	return &diode.Aggregate{
+		Prefix: diode.String("192.0.2.0/24"),
+		Rir: &diode.RIR{
+			Name:     diode.String("Example Name"),
+			Slug:     diode.String("example-slug"),
+			Metadata: diode.Metadata{"source": "example"},
+		},
+		Metadata: diode.Metadata{"source": "example"},
+	}
+}
+
+// AggregateExtended Creates a Aggregate with common optional fields.
+func AggregateExtended() *diode.Aggregate {
+	return &diode.Aggregate{
+		Prefix: diode.String("192.0.2.0/24"),
+		Rir: &diode.RIR{
+			Name:     diode.String("Example Name"),
+			Slug:     diode.String("example-slug"),
+			Metadata: diode.Metadata{"source": "example"},
+		},
+		Metadata:    diode.Metadata{"source": "example", "custom_key": "custom_value"},
+		Description: diode.String("Example description"),
+		Comments:    diode.String("Example comments"),
+	}
+}
+
+// AggregateExplicit Creates a Aggregate with fully nested objects and all common fields.
+func AggregateExplicit() *diode.Aggregate {
+	return &diode.Aggregate{
+		Prefix: diode.String("192.0.2.0/24"),
+		Rir: &diode.RIR{
+			Name:     diode.String("Example Name"),
+			Slug:     diode.String("example-slug"),
+			Metadata: diode.Metadata{"source": "example"},
+		},
+		Metadata:    diode.Metadata{"source": "example", "custom_key": "custom_value", "collected_at": "2024-01-15T10:30:00Z"},
+		Description: diode.String("Example description"),
+		Comments:    diode.String("Example comments"),
+		Tenant: &diode.Tenant{
+			Name:     diode.String("Example Name"),
+			Slug:     diode.String("example-slug"),
+			Metadata: diode.Metadata{"source": "example"},
+		},
+		Owner: &diode.Owner{
+			Name: diode.String("Example Name"),
+			Group: &diode.OwnerGroup{
+				Name:     diode.String("Example Name"),
+				Metadata: diode.Metadata{"source": "example"},
+			},
+			Metadata: diode.Metadata{"source": "example"},
+		},
+		Tags: []*diode.Tag{{Name: diode.String("production")}},
+	}
+}

docs/examples/asn/go.mod

@@ -0,0 +1,9 @@
+module asn
+
+go 1.25
+
+require github.com/netboxlabs/diode-sdk-go
+
+// Use local SDK for development and validation
+// When copying this example, remove the replace directive and update the require version above
+replace github.com/netboxlabs/diode-sdk-go => ../../..