Add DocFX

.github/workflows/build.yml

@@ -11,6 +11,9 @@ on:
       - main
   workflow_dispatch:
 
+  schedule:
+    - cron: "0 2 15-21 * 3"  # Runs at 02:00 UTC on the 3rd Wednesday of every month
+
 jobs:
   build:
     runs-on: windows-latest

.github/workflows/pages.yml

@@ -0,0 +1,82 @@
+name: Deploy content to Pages
+
+on:
+  push:
+    branches: ["main"]
+
+  workflow_dispatch:
+
+  schedule:
+    - cron: "0 2 15-21 * 3"  # Runs at 02:00 UTC on the 3rd Wednesday of every month
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      #url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Download DocFX
+        shell: pwsh
+        run: |
+          Invoke-WebRequest -Uri https://github.com/dotnet/docfx/releases/download/v2.77.0/docfx-win-x64-v2.77.0.zip -OutFile docfx.zip
+
+      - name: Extract DocFX
+        shell: pwsh
+        run: |
+          Expand-Archive -Path docfx.zip -DestinationPath ./docfx
+
+      - name: Download material.zip
+        shell: pwsh
+        run: |
+          Invoke-WebRequest -Uri https://github.com/ovasquez/docfx-material/releases/download/1.0.0/material.zip -OutFile material.zip
+
+      - name: Extract material.zip
+        shell: pwsh
+        run: |
+          Expand-Archive -Path material.zip -DestinationPath ./
+
+      - name: Add header to README.md
+        shell: pwsh
+        run: |
+          Add-Content -Path temp.md -Value "---"
+          Add-Content -Path temp.md -Value "outputFileName: index.html"
+          Add-Content -Path temp.md -Value "---"
+          Get-Content -Path README.md | Add-Content -Path temp.md
+          Move-Item -Path temp.md -Destination README.md -Force
+
+      - name: Build documentation
+        shell: pwsh
+        run: .\docfx\docfx.exe docfx.json
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: Documentation
+          path: |
+            ./_site
+
+      - name: Upload to Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site/'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -4,3 +4,6 @@
 **/.vs/**
 *.nupkg
 output*.json
+_site/
+docs/
+src/.manifest

README.md

@@ -1,11 +1,9 @@
-# AggregateConfigBuildTask
+# Aggregate Config Build Task
 
-**AggregateConfigBuildTask** is an MSBuild task that aggregates and transforms configuration files into more consumable formats like JSON, Azure ARM template parameters, YAML during the build process.
+[![NuGet Version](https://img.shields.io/nuget/v/AggregateConfigBuildTask)](https://www.nuget.org/packages/AggregateConfigBuildTask) [![GitHub Build Status](https://img.shields.io/github/actions/workflow/status/richardsondev/AggregateConfigBuildTask/build.yml?branch=main
+)](https://github.com/richardsondev/AggregateConfigBuildTask/actions/workflows/build.yml?query=branch%3Amain)
 
-## Links
-
-* NuGet.org: https://www.nuget.org/packages/AggregateConfigBuildTask
-* GitHub: https://github.com/richardsondev/AggregateConfigBuildTask
+**AggregateConfigBuildTask** is a cross-platform MSBuild task that aggregates and transforms configuration files into more consumable formats like JSON, Azure ARM template parameters, YAML during the build process.
 
 ## Features
 
@@ -14,6 +12,11 @@
 - Optionally include the source file name in each configuration entry.
 - Embed output files as resources in the assembly for easy inclusion in your project.
 
+## Links
+
+* NuGet.org: https://www.nuget.org/packages/AggregateConfigBuildTask
+* GitHub: https://github.com/richardsondev/AggregateConfigBuildTask
+
 ## Installation
 
 To install the `AggregateConfigBuildTask` NuGet package, run the following command:
@@ -42,13 +45,15 @@ Alternatively, add the following line to your `.csproj` file:
 | **AdditionalProperties** | A set of custom top-level properties to include in the final output. Use `ItemGroup` syntax to define key-value pairs. See [below](#additional-properties) for usage details. | | |
 | **IsQuietMode** | When true, only warning and error logs are generated by the task, suppressing standard informational output. | `true`, `false` | `false` |
 
-## File Types
+### File Types
 
-| File Type   | Extensions           |
-|-------------|----------------------|
-| **Json**    | `.json`              |
-| **Arm**     | `.json`              |
-| **Yaml**    | `.yml`, `.yaml`      |
+The `InputDirectory` will be scanned for files based on the specified `InputType`. The following table lists the file extensions that will be considered for each `InputType`:
+
+| **InputType** | **Extensions Scanned** |
+|---------------|------------------------|
+| `Json`        | `.json`                |
+| `Arm`         | `.json`                |
+| `Yaml`        | `.yml`, `.yaml`        |
 
 ## Usage
 
@@ -249,13 +254,117 @@ resources:
 }
 ```
 
+## Accessing Embedded Resources in C# Assemblies
+
+Embedding resources such as configuration files into your assembly allows you to package all necessary data within a single executable or library.
+
+In the following example, we'll demonstrate how to read and deserialize an embedded resource at runtime.
+
+### Embedded resource
+
+Consider the following YML configuration files that you want to merge and embed into your assembly:
+
+**configs/global.yml**
+```yml
+enabled: true
+```
+
+**configs/prod.yml**
+```yml
+environment: Production
+```
+
+### Project file reference
+
+Your project should contain a reference similar to below:
+
+**application.csproj**
+```xml
+<Target Name="AggregateConfigs" BeforeTargets="PrepareForBuild">
+  <AggregateConfig 
+    InputDirectory="configs"
+    OutputFile="out/output.json"
+    OutputType="Json" />
+
+  <ItemGroup>
+    <EmbeddedResource Include="out/output.json" />
+  </ItemGroup>
+</Target>
+```
+
+### Reading the embedded resource
+
+To access and deserialize the embedded JSON resource, use the following method:
+
+**application.cs**
+```csharp
+using System;
+using System.IO;
+using System.Reflection;
+using System.Text.Json;
+
+public static T LoadFromEmbeddedResource<T>(string resourceName)
+{
+    var assembly = Assembly.GetExecutingAssembly();
+    using var stream = assembly.GetManifestResourceStream(resourceName)
+        ?? throw new FileNotFoundException($"Resource '{resourceName}' not found in assembly.");
+
+    return JsonSerializer.Deserialize<T>(stream, new JsonSerializerOptions
+    {
+        PropertyNameCaseInsensitive = true
+    }) ?? throw new InvalidOperationException("Failed to deserialize resource.");
+}
+```
+
+### Defining the Configuration Class
+
+Create a class that matches the structure of your configuration:
+
+```csharp
+public class AppConfig
+{
+    public bool Enabled { get; set; }
+    public string Environment { get; set; }
+}
+```
+
+### Loading and Using the Configuration
+
+You can now load and use the configuration data as follows:
+
+```csharp
+var applicationConfig = LoadFromEmbeddedResource<AppConfig>("YourAssemblyName.output.json");
+
+bool enabled = applicationConfig.Enabled; 
+Console.WriteLine($"Enabled: {enabled}"); // Outputs "True"
+
+string environment = applicationConfig.Environment; 
+Console.WriteLine($"Environment: {environment}"); // Outputs "Production"
+```
+
+**Note:** Replace `"YourAssemblyName.output.json"` with the actual resource name, which typically includes the assembly name and the output file name.
+
+### Finding the Correct Resource Name
+
+If you're unsure about the exact resource name, you can retrieve all resource names in the assembly by adding the following code and inspecting the output:
+
+```csharp
+string[] resourceNames = Assembly.GetExecutingAssembly().GetManifestResourceNames();
+foreach (var name in resourceNames)
+{
+    Console.WriteLine(name);
+}
+```
+
+This will list all embedded resources, allowing you to confirm the correct name to use when loading the resource.
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE](https://github.com/richardsondev/AggregateConfigBuildTask/blob/main/LICENSE) file for details.
 
 ## Third-Party Libraries
 
-This project leverages the following third-party libraries:
+This project leverages the following third-party libraries that are bundled with the package:
 
 - **[YamlDotNet](https://github.com/aaubry/YamlDotNet)**\
   __Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014 Antoine Aubry and contributors__\

docfx.json

@@ -0,0 +1,66 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "src/**/*.csproj",
+            "images/icon/*"
+          ],
+          "exclude": [
+            "**/bin/**",
+            "**/obj/**"
+          ]
+        }
+      ],
+      "dest": "./docs"
+    }
+  ],
+  "build": {
+    "globalMetadata": {
+      "_appTitle": "Aggregate Config Build Task",
+      "_appName": "AggregateConfigBuildTask",
+      "_enableSearch": "true",
+      "_appLogoPath": "image/icon/icon_50.png",
+      "_appFaviconPath": "image/icon/favicon.ico",
+      "_enableNewTab": "true",
+      "_disableContribution": "false",
+      "includePrivateMembers": "true",
+      "_appFooter": "<span>Copyright &copy; 2024 <a href=\"https://github.com/richardsondev\">Billy Richardson</a>. Generated with <a href=\"https://dotnet.github.io/docfx\">DocFX</a></span>"
+    },
+    "resource": [
+      {
+        "files": [
+          "image/**"
+        ]
+      }
+    ],
+    "content": [
+      {
+        "files": "docs/*.yml",
+        "dest": "./"
+      },
+      {
+        "files": [
+          "README.md",
+          "toc.yml"
+        ],
+        "dest": "./"
+      }
+    ],
+    "dest": "_site",
+    "sitemap": {
+      "baseUrl": "https://richardsondev.github.io/AggregateConfigBuildTask",
+      "priority": 0.1,
+      "changefreq": "monthly"
+    },
+    "postProcessors": [
+      "ExtractSearchIndex"
+    ],
+    "template": [
+      "statictoc",
+      "modern",
+      "material"
+    ]
+  }
+}

src/Task/AggregateConfigBuildTask.csproj

@@ -16,9 +16,9 @@
     <PropertyGroup>
         <PackageId>AggregateConfigBuildTask</PackageId>
         <Version Condition=" '$(Version)' == '' ">0.0.1</Version>
-        <Authors>richardsondev</Authors>
+        <Authors>Billy Richardson</Authors>
         <Owner>richardsondev</Owner>
-        <Company>richardsondev</Company>
+        <Company>https://richardson.software</Company>
         <Description>Merges configuration files at build time, allowing them to be embedded as resources for streamlined deployment and access.</Description>
         <PackageTags>yaml, json, arm, build, configuration, msbuild</PackageTags>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
@@ -53,11 +53,9 @@
         <None Include="$(OutputPath)/Microsoft.Bcl.AsyncInterfaces.dll" Pack="true" PackagePath="/tasks/netstandard2.0/" />
         <None Include="$(OutputPath)/System.Text.Json.dll" Pack="true" PackagePath="/tasks/netstandard2.0/" />
         <None Include="$(OutputPath)/YamlDotNet.dll" Pack="true" PackagePath="/tasks/netstandard2.0/" />
-        <None Include="$(PkgYamlDotNet)/LICENSE.txt" Pack="true" PackagePath="/licenses/YamlDotNet">
-            <Link>licenses/YamlDotNet/LICENSE.txt</Link>
-        </None>
         <None Include="$(OutputPath)/YamlDotNet.System.Text.Json.dll" Pack="true" PackagePath="/tasks/netstandard2.0/" />
         <None Include="build/AggregateConfigBuildTask.targets" Pack="true" PackagePath="/build/AggregateConfigBuildTask.targets" />
+        <None Include="../ThirdPartyNotices.txt" Pack="true" PackagePath="/" />
         <None Include="../../LICENSE" Pack="true" PackagePath="/licenses/">
             <Link>licenses/LICENSE</Link>
         </None>

src/Task/AssemblyInfo.cs

@@ -4,5 +4,5 @@
 [assembly: InternalsVisibleTo("AggregateConfig.Tests.Unit")]
 
 [assembly: AssemblyMetadata("Copyright", "2024")]
-[assembly: AssemblyMetadata("Author", "richardsondev")]
+[assembly: AssemblyMetadata("Author", "Billy Richardson")]
 [assembly: AssemblyMetadata("RepositoryUrl", "https://github.com/richardsondev/AggregateConfigBuildTask")]