Merge pull request #83 from Chris-Wolfgang/copilot/fix-docfx-configuration

Fix DocFX configuration to build API documentation via CI/CD workflow

Author: Chris-Wolfgang

.github/workflows/docfx.yaml

@@ -40,16 +40,18 @@ jobs:
 
       - name: Verify build output
         run: |
-          if [ ! -d "docfx_project/_site" ]; then
-            echo "Error: _site directory not found!"
+          if [ ! -d "docs" ]; then
+            echo "Error: docs directory not found!"
             exit 1
           fi
-          echo "Build successful. Contents of _site:"
-          ls -la docfx_project/_site
+          echo "Build successful. Contents of docs:"
+          ls -la docs
+          echo "API documentation:"
+          ls -la docs/api
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docfx_project/_site
+          publish_dir: ./docs
           force_orphan: true

.gitignore

@@ -424,3 +424,7 @@ CoverageReport/
 # DocFX generated files
 docfx_project/_site/
 docfx_project/obj/
+
+# Generated documentation (built by CI/CD)
+docs/*
+!docs/.gitkeep

README.md

@@ -146,6 +146,40 @@ dotnet format --verify-no-changes
 
 See [README-FORMATTING.md](README-FORMATTING.md) for detailed formatting guidelines.
 
+### Building Documentation
+
+This project uses [DocFX](https://dotnet.github.io/docfx/) to generate API documentation:
+
+```bash
+# Install DocFX (one-time setup)
+dotnet tool install -g docfx
+
+# Generate API metadata and build documentation
+cd docfx_project
+docfx metadata  # Extract API metadata from source code
+docfx build     # Build HTML documentation
+
+# Documentation is generated in the docs/ folder at the repository root
+```
+
+The documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch.
+
+**Local Preview:**
+```bash
+# Serve documentation locally (with live reload)
+cd docfx_project
+docfx build --serve
+
+# Open http://localhost:8080 in your browser
+```
+
+**Documentation Structure:**
+- `docfx_project/` - DocFX configuration and source files
+- `docs/` - Generated HTML documentation (published to GitHub Pages)
+- `docfx_project/index.md` - Main landing page content
+- `docfx_project/docs/` - Additional documentation articles
+- `docfx_project/api/` - Auto-generated API reference YAML files
+
 ---
 
 ## 🤝 Contributing

docfx_project/api/Wolfgang.Extensions.IAsyncEnumerable.IAsyncEnumerableExtensions.yml

@@ -54,7 +54,7 @@ items:
   source:
     remote:
       path: src/Wolfgang.Extensions.IAsyncEnumerable/IAsyncEnumerableExtensions.cs
-      branch: copilot/fix-docfx-documentation-build
+      branch: main
       repo: https://github.com/Chris-Wolfgang/IAsyncEnumerable-Extensions
     id: ChunkAsync
     path: ../src/Wolfgang.Extensions.IAsyncEnumerable/IAsyncEnumerableExtensions.cs

docfx_project/docfx.json

@@ -36,7 +36,7 @@
         ]
       }
     ],
-    "output": "_site",
+    "output": "../docs",
     "template": [
       "default",
       "modern",
@@ -50,6 +50,7 @@
       "_disableSidebar": false,
       "_disableTocFilter": false,
       "_enableDarkMode": true,
+      "_baseUrl": "/IAsyncEnumerable-Extensions/",
       "pdf": true
     }
   }