Add DocFX metadata and build steps to workflow#49
Conversation
Added two steps to pr.yaml: one to generate DocFX metadata and another to build the DocFX site within the docfx_project directory. This automates documentation generation as part of the CI workflow.
There was a problem hiding this comment.
Pull request overview
This PR adds automated documentation generation to the CI workflow by integrating DocFX metadata generation and site building steps into the pull request validation process.
Key Changes:
- Added DocFX metadata generation step to extract API documentation from source code
- Added DocFX site build step to compile the documentation into a static site
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| run: dotnet docfx metadata docfx.json | ||
|
|
||
| - name: Build DocFX site | ||
| working-directory: docfx_project | ||
| run: dotnet docfx build docfx.json |
There was a problem hiding this comment.
The DocFX commands will fail because docfx is installed as a local tool (line 38-41) but is being invoked directly. When docfx is installed as a local tool using "dotnet tool install", it needs to be invoked using "dotnet tool run docfx" or just "dotnet docfx" instead of "dotnet docfx metadata" and "dotnet docfx build". The current commands should be changed to use the local tool properly.
| run: dotnet docfx metadata docfx.json | |
| - name: Build DocFX site | |
| working-directory: docfx_project | |
| run: dotnet docfx build docfx.json | |
| run: dotnet tool run docfx metadata docfx.json | |
| - name: Build DocFX site | |
| working-directory: docfx_project | |
| run: dotnet tool run docfx build docfx.json |
| - name: Generate DocFX metadata | ||
| working-directory: docfx_project | ||
| run: dotnet docfx metadata docfx.json | ||
|
|
||
| - name: Build DocFX site |
There was a problem hiding this comment.
These DocFX steps will run on all OS matrix values (ubuntu-latest, windows-latest, macos-latest), which is inefficient and unnecessary since documentation only needs to be generated once. Consider adding an "if: runner.os == 'Windows'" or "if: runner.os == 'Linux'" condition to these steps to run them on only one platform, similar to how other steps in this workflow are conditionally executed.
| - name: Generate DocFX metadata | |
| working-directory: docfx_project | |
| run: dotnet docfx metadata docfx.json | |
| - name: Build DocFX site | |
| - name: Generate DocFX metadata | |
| if: runner.os == 'Windows' | |
| working-directory: docfx_project | |
| run: dotnet docfx metadata docfx.json | |
| - name: Build DocFX site | |
| if: runner.os == 'Windows' |
| working-directory: docfx_project | ||
| run: dotnet docfx metadata docfx.json | ||
|
|
||
| - name: Build DocFX site | ||
| working-directory: docfx_project |
There was a problem hiding this comment.
These steps lack error handling. If the DocFX metadata generation or build fails, the entire workflow will fail. Consider adding "continue-on-error: true" to these steps, similar to how the test coverage steps (lines 93, 119) handle potential failures, especially since documentation generation is a non-critical part of PR validation.
| working-directory: docfx_project | |
| run: dotnet docfx metadata docfx.json | |
| - name: Build DocFX site | |
| working-directory: docfx_project | |
| working-directory: docfx_project | |
| continue-on-error: true | |
| run: dotnet docfx metadata docfx.json | |
| - name: Build DocFX site | |
| working-directory: docfx_project | |
| continue-on-error: true |
Added if: runner.os == 'Windows' to the "Generate DocFX metadata" and "Build DocFX site" steps in pr.yaml, ensuring these steps execute only on Windows environments. This prevents execution on non-Windows runners where DocFX may not be supported.
Refactored pr.yaml to run on ubuntu-latest only, removing matrix OS strategy and consolidating build/test steps. Test projects are now auto-discovered and run in a loop with coverage collected for each. Coverage reporting and threshold checks are now bash-based for Linux compatibility. Artifact uploads and DevSkim security scans are streamlined and no longer OS-specific. Removed DocFX documentation build steps for a simpler, more maintainable workflow.
Added two steps to pr.yaml: one to generate DocFX metadata and another to build the DocFX site within the docfx_project directory. This automates documentation generation as part of the CI workflow.
Description
Fixes/Complete # (issue)
Type of change
Please delete options that are not relevant.
How Has This Been Tested?
Checklist
Screenshots (if applicable)
Additional context