Add documentation generation tools

api/index.md

@@ -0,0 +1,3 @@
+# API Index
+
+This is the API index for the Weaviate C# client documentation.

docfx.json

@@ -0,0 +1,36 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": ["src/Weaviate.Client/**/*.csproj"]
+        }
+      ],
+      "dest": "api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": ["api/index.md"]
+      },
+      {
+        "files": ["docs/**/*.md"]
+      }
+    ],
+    "resource": [
+      {
+        "files": ["docs/images/**"]
+      }
+    ],
+    "overwrite": [
+      {
+        "files": ["docs/overwrite/**/*.md"]
+      }
+    ],
+    "dest": "_site",
+    "globalMetadata": {
+      "_appTitle": "Weaviate C# Client Documentation"
+    }
+  }
+}

docs/DOCUMENTATION.md

@@ -0,0 +1,3 @@
+# Weaviate C# Client Documentation
+
+This document describes the XML documentation and tooling for generating API docs for the Weaviate C# client.

docs/DOCUMENTATION_TOOLS.md

@@ -0,0 +1,3 @@
+# Documentation Tools
+
+This document describes the tools and scripts used to generate documentation for the Weaviate C# client.

scripts/README.md

@@ -0,0 +1,3 @@
+# Documentation Scripts
+
+This directory contains scripts for generating documentation for the Weaviate C# client.

scripts/generate-docs-html.ps1

@@ -0,0 +1 @@
+# PowerShell script to generate HTML docs

scripts/generate-docs-html.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+# Bash script to generate HTML docs

scripts/generate-docs-markdown.py

@@ -0,0 +1 @@
+# Python script to generate markdown docs

scripts/generate-docs-markdown.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+# Bash script to generate markdown docs

scripts/generate-docs-xmldocmd.ps1

@@ -0,0 +1 @@
+# PowerShell script to generate XMLDocMD docs

scripts/generate-docs-xmldocmd.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+# Bash script to generate XMLDocMD docs

src/Example/Cat.cs

@@ -1,12 +1,34 @@
 namespace Example;
 
+/// <summary>
+/// The cat
+/// </summary>
 public record Cat
 {
+    /// <summary>
+    /// Gets or sets the value of the counter
+    /// </summary>
     public int Counter { get; set; }
+
+    /// <summary>
+    /// Gets or sets the value of the color
+    /// </summary>
     public string? Color { get; set; }
+
+    /// <summary>
+    /// Gets or sets the value of the breed
+    /// </summary>
     public string? Breed { get; set; }
+
+    /// <summary>
+    /// Gets or sets the value of the name
+    /// </summary>
     public string? Name { get; set; }
 
+    /// <summary>
+    /// Returns the string
+    /// </summary>
+    /// <returns>The string</returns>
     public override string ToString()
     {
         return $"Cat ({Counter}) {{ Name: {Name}, Color: {Color}, Breed: {Breed} }}";

src/Example/DependencyInjectionExample.cs

@@ -11,6 +11,9 @@ namespace Example;
 /// </summary>
 public class DependencyInjectionExample
 {
+    /// <summary>
+    /// Runs
+    /// </summary>
     public static async Task Run()
     {
         // Build host with dependency injection
@@ -52,9 +55,21 @@ public static async Task Run()
 /// </summary>
 public class CatService
 {
+    /// <summary>
+    /// The weaviate
+    /// </summary>
     private readonly WeaviateClient _weaviate;
+
+    /// <summary>
+    /// The logger
+    /// </summary>
     private readonly ILogger<CatService> _logger;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CatService"/> class
+    /// </summary>
+    /// <param name="weaviate">The weaviate</param>
+    /// <param name="logger">The logger</param>
     public CatService(WeaviateClient weaviate, ILogger<CatService> logger)
     {
         _weaviate = weaviate;
@@ -67,6 +82,9 @@ public CatService(WeaviateClient weaviate, ILogger<CatService> logger)
         );
     }
 
+    /// <summary>
+    /// Demonstrates the usage
+    /// </summary>
     public async Task DemonstrateUsageAsync()
     {
         // Check if client is initialized
@@ -149,6 +167,9 @@ await _weaviate.Collections.Create<Cat>(
 /// </summary>
 public class ConfigurationExample
 {
+    /// <summary>
+    /// Runs
+    /// </summary>
     public static async Task RunAsync()
     {
         var host = Host.CreateDefaultBuilder()
@@ -180,6 +201,9 @@ public static async Task RunAsync()
 /// </summary>
 public class LazyInitializationExample
 {
+    /// <summary>
+    /// Runs
+    /// </summary>
     public static async Task RunAsync()
     {
         var host = Host.CreateDefaultBuilder()
@@ -213,6 +237,9 @@ public static async Task RunAsync()
 /// </summary>
 public class ConnectHelperExample
 {
+    /// <summary>
+    /// Runs
+    /// </summary>
     public static async Task RunAsync()
     {
         // These still work! Fully async, no blocking

src/Example/DifferentConfigsExample.cs

@@ -11,6 +11,9 @@ namespace Example;
 /// </summary>
 public class DifferentConfigsExample
 {
+    /// <summary>
+    /// Runs
+    /// </summary>
     public static async Task Run()
     {
         var host = Host.CreateDefaultBuilder()
@@ -124,15 +127,28 @@ public static async Task Run()
     }
 }
 
+/// <summary>
+/// The multi config service class
+/// </summary>
 public class MultiConfigService
 {
+    /// <summary>
+    /// The factory
+    /// </summary>
     private readonly IWeaviateClientFactory _factory;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MultiConfigService"/> class
+    /// </summary>
+    /// <param name="factory">The factory</param>
     public MultiConfigService(IWeaviateClientFactory factory)
     {
         _factory = factory;
     }
 
+    /// <summary>
+    /// Shows the different configs
+    /// </summary>
     public async Task ShowDifferentConfigsAsync()
     {
         Console.WriteLine("=== Different Client Configurations ===\n");
@@ -194,6 +210,10 @@ public async Task ShowDifferentConfigsAsync()
         await UseAnalyticsClient(analyticsClient);
     }
 
+    /// <summary>
+    /// Uses the production client using the specified client
+    /// </summary>
+    /// <param name="client">The client</param>
     private async Task UseProductionClient(WeaviateClient client)
     {
         // Production has strict timeouts and requires auth
@@ -202,6 +222,10 @@ private async Task UseProductionClient(WeaviateClient client)
         // This will use 30s query timeout configured above
     }
 
+    /// <summary>
+    /// Uses the local client using the specified client
+    /// </summary>
+    /// <param name="client">The client</param>
     private async Task UseLocalClient(WeaviateClient client)
     {
         // Local has no auth and longer timeouts for debugging
@@ -210,6 +234,10 @@ private async Task UseLocalClient(WeaviateClient client)
         // This will use 300s query timeout - perfect for debugging
     }
 
+    /// <summary>
+    /// Uses the analytics client using the specified client
+    /// </summary>
+    /// <param name="client">The client</param>
     private async Task UseAnalyticsClient(WeaviateClient client)
     {
         // Analytics has custom ports and longer timeouts for slow queries
@@ -219,14 +247,34 @@ private async Task UseAnalyticsClient(WeaviateClient client)
     }
 }
 
+/// <summary>
+/// The product class
+/// </summary>
 public class Product
 {
+    /// <summary>
+    /// Gets or sets the value of the name
+    /// </summary>
     public string? Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the value of the price
+    /// </summary>
     public decimal Price { get; set; }
 }
 
+/// <summary>
+/// The metric class
+/// </summary>
 public class Metric
 {
+    /// <summary>
+    /// Gets or sets the value of the name
+    /// </summary>
     public string? Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the value of the value
+    /// </summary>
     public double Value { get; set; }
 }

src/Example/MultipleClientsExample.cs

@@ -12,6 +12,9 @@ namespace Example;
 /// </summary>
 public class MultipleClientsExample
 {
+    /// <summary>
+    /// Runs
+    /// </summary>
     public static async Task Run()
     {
         var host = Host.CreateDefaultBuilder()
@@ -74,9 +77,21 @@ public static async Task Run()
 /// </summary>
 public class MultiDatabaseService
 {
+    /// <summary>
+    /// The client factory
+    /// </summary>
     private readonly IWeaviateClientFactory _clientFactory;
+
+    /// <summary>
+    /// The logger
+    /// </summary>
     private readonly ILogger<MultiDatabaseService> _logger;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="MultiDatabaseService"/> class
+    /// </summary>
+    /// <param name="clientFactory">The client factory</param>
+    /// <param name="logger">The logger</param>
     public MultiDatabaseService(
         IWeaviateClientFactory clientFactory,
         ILogger<MultiDatabaseService> logger
@@ -86,6 +101,9 @@ ILogger<MultiDatabaseService> logger
         _logger = logger;
     }
 
+    /// <summary>
+    /// Demonstrates the multiple clients
+    /// </summary>
     public async Task DemonstrateMultipleClientsAsync()
     {
         _logger.LogInformation("=== Multiple Weaviate Clients Example ===\n");
@@ -104,6 +122,11 @@ public async Task DemonstrateMultipleClientsAsync()
         await TestLocallyAsync(localClient);
     }
 
+    /// <summary>
+    /// Syncs the data between environments using the specified prod client
+    /// </summary>
+    /// <param name="prodClient">The prod client</param>
+    /// <param name="stagingClient">The staging client</param>
     private async Task SyncDataBetweenEnvironmentsAsync(
         WeaviateClient prodClient,
         WeaviateClient stagingClient
@@ -130,6 +153,10 @@ WeaviateClient stagingClient
         _logger.LogInformation("Synced to staging environment");
     }
 
+    /// <summary>
+    /// Tests the locally using the specified local client
+    /// </summary>
+    /// <param name="localClient">The local client</param>
     private async Task TestLocallyAsync(WeaviateClient localClient)
     {
         _logger.LogInformation("\nTesting locally...");
@@ -147,13 +174,24 @@ private async Task TestLocallyAsync(WeaviateClient localClient)
 /// </summary>
 public class OnDemandClientService
 {
+    /// <summary>
+    /// The client factory
+    /// </summary>
     private readonly IWeaviateClientFactory _clientFactory;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="OnDemandClientService"/> class
+    /// </summary>
+    /// <param name="clientFactory">The client factory</param>
     public OnDemandClientService(IWeaviateClientFactory clientFactory)
     {
         _clientFactory = clientFactory;
     }
 
+    /// <summary>
+    /// Processes the data from environment using the specified environment
+    /// </summary>
+    /// <param name="environment">The environment</param>
     public async Task ProcessDataFromEnvironmentAsync(string environment)
     {
         // Get the appropriate client based on runtime logic
@@ -171,6 +209,9 @@ public async Task ProcessDataFromEnvironmentAsync(string environment)
 /// </summary>
 public class ConfigurationBasedMultiClientExample
 {
+    /// <summary>
+    /// Runs
+    /// </summary>
     public static async Task RunAsync()
     {
         /*