docs: add API reference publishing with DocFX (#63)

Author: rian-be

.github/workflows/pr-check.yml

@@ -47,6 +47,24 @@ jobs:
       - name: Check dependency health
         run: python3 -m scripts.dependencies.check_package_health --solution ModularityKit.Mutator.slnx
 
+  docs:
+    name: docs
+    runs-on: ubuntu-latest
+    needs: build
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Install DocFX
+        run: dotnet tool update -g docfx
+
+      - name: Build docs
+        run: docfx docfx.json
+
   tests:
     name: ${{ matrix.name }}
     runs-on: ubuntu-latest
@@ -177,6 +195,7 @@ jobs:
     needs:
       - build
       - dependency-health
+      - docs
       - tests
       - examples-core
       - examples-governance
@@ -188,13 +207,15 @@ jobs:
         run: |
           echo "build: ${{ needs.build.result }}"
           echo "dependency-health: ${{ needs.dependency-health.result }}"
+          echo "docs: ${{ needs.docs.result }}"
           echo "tests: ${{ needs.tests.result }}"
           echo "examples-core: ${{ needs.examples-core.result }}"
           echo "examples-governance: ${{ needs.examples-governance.result }}"
           echo "examples-governance-redis: ${{ needs.examples-governance-redis.result }}"
 
           if [ "${{ needs.build.result }}" != "success" ] || \
              [ "${{ needs.dependency-health.result }}" != "success" ] || \
+             [ "${{ needs.docs.result }}" != "success" ] || \
              [ "${{ needs.tests.result }}" != "success" ] || \
              [ "${{ needs.examples-core.result }}" != "success" ] || \
              [ "${{ needs.examples-governance.result }}" != "success" ] || \

.gitignore

@@ -1,5 +1,6 @@
 .idea/
 bin/
 obj/
+_site/
 __pycache__/
 *.pyc

Directory.Build.props

@@ -1,5 +1,5 @@
 <Project>
   <PropertyGroup>
-    <BaseIntermediateOutputPath>$(MSBuildProjectDirectory)/obj/$(MSBuildProjectName)/</BaseIntermediateOutputPath>
+    <BaseIntermediateOutputPath>$(MSBuildThisFileDirectory)obj/$(MSBuildProjectName)/</BaseIntermediateOutputPath>
   </PropertyGroup>
 </Project>

Docs/API/API-Reference.md

@@ -132,5 +132,5 @@ in-memory provider.
 
 - [`src/Redis/README.md`](../../src/Redis/README.md)
 - [`Examples/Governance/RedisQueries/README.md`](../../Examples/Governance/RedisQueries/README.md)
-- [`API-Reference.md`](API-Reference.md)
+- [`Reference.md`](Reference.md)
 - [Governance API](API.md)

Docs/API/Redis.md

@@ -0,0 +1,18 @@
+# API Reference
+
+DocFX generates the public API reference from the compiled assemblies and XML documentation files.
+
+## Included packages
+
+- `ModularityKit.Mutator`
+- `ModularityKit.Mutator.Governance`
+- `ModularityKit.Mutator.Governance.Redis`
+
+## Build locally
+
+```bash
+dotnet tool update -g docfx
+docfx docfx.json
+```
+
+The rendered API pages appear under the `API` section of the generated site.

Docs/API/Reference.md

@@ -36,3 +36,15 @@ python3 -m scripts.dependencies.check_package_health --solution ModularityKit.Mu
 ```
 
 The check reports vulnerable packages as a failing condition and prints outdated packages for review. When a package needs attention, update the affected `PackageReference` version in the owning project and rerun the check.
+
+## Documentation
+
+Build the DocFX site locally with:
+
+```bash
+dotnet tool update -g docfx
+docfx docfx.json
+```
+
+The generated site includes the conceptual docs under `Docs/` and the public API reference for the
+three published packages.