docs(source): autogenerate docs for sources with go-doc like style

Makefile

@@ -178,6 +178,11 @@ generate-flags-documentation:
 generate-metrics-documentation:
 	go run internal/gen/docs/metrics/main.go
 
+.PHONY: generate-sources-documentation
+#? generate-sources-documentation: Generate documentation (docs/sources/index.md)
+generate-sources-documentation:
+	go run internal/gen/docs/sources/main.go
+
 #? pre-commit-install: Install pre-commit hooks
 pre-commit-install:
 	@pre-commit install

docs/contributing/sources-and-providers.md

@@ -1,3 +1,10 @@
+---
+tags:
+  - sources
+  - providers
+  - contributing
+---
+
 # Sources and Providers
 
 ExternalDNS supports swapping out endpoint **sources** and DNS **providers** and both sides are pluggable. There currently exist multiple sources for different provider implementations.
@@ -29,6 +36,37 @@ All sources live in package `source`.
 * `CRDSource`: returns a list of Endpoint objects sourced from the spec of CRD objects. For more details refer to [CRD source](../sources/crd.md) documentation.
 * `EmptySource`: returns an empty list of Endpoint objects for the purpose of testing and cleaning out entries.
 
+### Adding New Sources
+
+When creating a new source, add the following annotations above the source struct definition:
+
+```go
+// myNewSource is an implementation of Source for MyResource objects.
+//
+// +externaldns:source:name=my-new-source
+// +externaldns:source:category=Kubernetes Core
+// +externaldns:source:description=Creates DNS entries from MyResource objects
+// +externaldns:source:resources=MyResource<Kind.apigroup.subdomain.domain>
+// +externaldns:source:filters=
+// +externaldns:source:namespace=all,single
+// +externaldns:source:fqdn-template=false
+type myNewSource struct {
+    // ... fields
+}
+```
+
+**Annotation Reference:**
+
+* `+externaldns:source:name` - The CLI name used with `--source` flag (required)
+* `+externaldns:source:category` - Category for documentation grouping (required)
+* `+externaldns:source:description` - Short description of what the source does (required)
+* `+externaldns:source:resources` - Kubernetes resources watched (comma-separated). Convention `Kind.apigroup.subdomain.domain`
+* `+externaldns:source:filters` - Supported filter types (annotation, label)
+* `+externaldns:source:namespace` - Namespace support: comma-separated values (all, single, multiple)
+* `+externaldns:source:fqdn-template` - FQDN template support (true, false)
+
+After adding annotations, run `make generate-sources-documentation` to update sources file.
+
 ## Providers
 
 Providers are an abstraction over any kind of sink for desired Endpoints, e.g.:

docs/sources/index.md

@@ -0,0 +1,75 @@
+---
+tags:
+  - sources
+  - autogenerated
+---
+
+# Supported Sources
+
+<!-- THIS FILE MUST NOT BE EDITED BY HAND -->
+<!-- ON NEW SOURCE ADDED PLEASE RUN 'make generate-sources-documentation' -->
+<!-- markdownlint-disable MD013 -->
+
+ExternalDNS supports multiple sources for discovering DNS records. Each source watches specific Kubernetes or cloud platform resources and generates DNS records based on their configuration.
+
+## Overview
+
+Sources are responsible for:
+
+- Watching Kubernetes resources or external APIs
+- Extracting DNS information from annotations and resource specifications
+- Generating DNS endpoint records for providers to consume
+
+## Available Sources
+
+| **Source Name** | Resources | Filters | Namespace | FQDN Template | Category |
+|:----------------|:----------|:--------|:----------|:--------------|:---------|
+| **ambassador-host** | Host.getambassador.io | annotation,label | all,single | false | ingress controllers |
+| **cloudfoundry** | CloudFoundry Routes |  |  | false | cloud platforms |
+| **connector** | Remote TCP Server |  |  | false | special |
+| **contour-httpproxy** | HTTPProxy.projectcontour.io | annotation | all,single | true | ingress controllers |
+| **crd** | DNSEndpoint.k8s.io | annotation,label | all,single | false | externaldns |
+| **empty** | None |  |  | false | testing |
+| **f5-transportserver** | TransportServer.cis.f5.com | annotation | all,single | false | load balancers |
+| **f5-virtualserver** | VirtualServer.cis.f5.com | annotation | all,single | false | load balancers |
+| **fake** | Fake Endpoints |  |  | true | testing |
+| **gateway-grpcroute** | GRPCRoute.gateway.networking.k8s.io | annotation,label | all,single | false | gateway api |
+| **gateway-httproute** | HTTPRoute.gateway.networking.k8s.io | annotation,label | all,single | false | gateway api |
+| **gateway-tcproute** | TCPRoute.gateway.networking.k8s.io | annotation,label | all,single | false | gateway api |
+| **gateway-tlsroute** | TLSRoute.gateway.networking.k8s.io | annotation,label | all,single | false | gateway api |
+| **gateway-udproute** | UDPRoute.gateway.networking.k8s.io | annotation,label | all,single | true | gateway api |
+| **gloo-proxy** | Proxy.gloo.solo.io |  | all,single | false | service mesh |
+| **ingress** | Ingress | annotation,label | all,single | true | kubernetes core |
+| **istio-gateway** | Gateway.networking.istio.io | annotation | all,single | true | service mesh |
+| **istio-virtualservice** | VirtualService.networking.istio.io | annotation | all,single | true | service mesh |
+| **kong-tcpingress** | TCPIngress.configuration.konghq.com | annotation | all,single | false | ingress controllers |
+| **node** | Node | annotation,label | all | true | kubernetes core |
+| **openshift-route** | Route.route.openshift.io | annotation,label | all,single | true | openshift |
+| **pod** | Pod | annotation,label | all,single | true | kubernetes core |
+| **service** | Service | annotation,label | all,single | true | kubernetes core |
+| **skipper-routegroup** | RouteGroup.zalando.org | annotation | all,single | true | ingress controllers |
+| **traefik-proxy** | IngressRoute.traefik.io<br/>IngressRouteTCP.traefik.io<br/>IngressRouteUDP.traefik.io | annotation | all,single | false | ingress controllers |
+
+## Usage
+
+To use a specific source, configure ExternalDNS with the `--source` flag:
+
+```bash
+external-dns --source=service --source=ingress
+```
+
+Multiple sources can be combined to watch different resource types simultaneously.
+
+## Source Categories
+
+- **Kubernetes Core**: Native Kubernetes resources (Service, Ingress, Pod, Node)
+- **ExternalDNS**: Native ExternalDNS resources
+- **Gateway API**: Kubernetes Gateway API resources (Gateway, HTTPRoute, etc.)
+- **Service Mesh**: Service mesh implementations (Istio, Gloo)
+- **Ingress Controllers**: Third-party ingress controller resources (Contour, Traefik, Ambassador, etc.)
+- **Load Balancers**: Load balancer specific resources (F5)
+- **OpenShift**: OpenShift specific resources (Route)
+- **Cloud Platforms**: Cloud platform integrations (Cloud Foundry)
+- **Wrappers**: Source wrappers that modify or combine other sources
+- **Special**: Special purpose sources (connector, empty)
+- **Testing**: Sources used for testing purposes

internal/gen/docs/metrics/main_test.go

@@ -79,7 +79,7 @@ func TestMetricsMdUpToDate(t *testing.T) {
 	reg := metrics.RegisterMetric
 	actual, err := generateMarkdownTable(reg, false)
 	assert.NoError(t, err)
-	assert.Contains(t, string(expected), actual)
+	assert.Contains(t, string(expected), actual, "expected file 'docs/monitoring/metrics.md' to be up to date. execute 'make generate-metrics-documentation")
 }
 
 func TestMetricsMdExtraMetricAdded(t *testing.T) {