Add user guide PDF generation

[Copilot]

Pull Request

Description

Implements automated user guide PDF generation following the established SonarMark pattern. BuildMark now publishes comprehensive usage documentation as part of the build artifacts.

Changes:

• docs/guide/: New folder structure with Pandoc configuration and 520-line comprehensive guide covering installation, CLI reference, use cases, troubleshooting, and best practices
• Guide structure: Restructured with 10 primary-level sections (Introduction, Installation, Getting Started, Command-Line Options, Common Use Cases, Report Format, Running Self-Validation, Best Practices, Troubleshooting, Additional Resources) for proper chapter-style PDF navigation instead of nesting all content under a single heading
• .github/workflows/build.yaml: Added Pandoc→HTML→PDF generation steps for user guide, integrated into existing build-docs job
• Artifact output: BuildMark User Guide.pdf generated in docs/ and included in documents artifact

The guide structure mirrors existing documentation (buildnotes, requirements, tracematrix, quality), ensuring consistency in the build pipeline.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Implements user guide PDF generation as requested.

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All tests pass: dotnet test --configuration Release
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• Spell checker passes: cspell "**/*.{md,cs}"
• Markdown linter passes: markdownlint "**/*.md"
• YAML linter passes: yamllint '**/*.{yml,yaml}'

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

No code changes—documentation and workflow only. PDF generation tested locally with Pandoc/Weasyprint toolchain. The workflow additions are positioned between build notes and requirements generation, maintaining logical document ordering in the pipeline.

The guide uses primary-level headings for major sections to create a proper chapter structure in the generated PDF, with all subsections properly nested. This provides better navigation and organization in the final PDF document.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature]: User Guide</issue_title>
<issue_description>### Problem Statement

BuildMark should publish a user guide PDF.

Proposed Solution

Have BuildMark publish a user guide - follow https://github.com/demaconsulting/SonarMark for an example of doing this; including:

• add the docs/guide folder with the pandoc template
• add the document building steps to the build-docs job
• generate the pdf in the docs folder so it gets picked up in the documents artifact

Remember that pandoc is configured to generate table-of-contents, so the markdown doesn't need it manually added.

Alternatives Considered

No response

Usage Examples

Benefits

Usage information available to users.

Priority

High - Blocking my use case

Willingness to Contribute

Yes, I can submit a pull request

Additional Context

No response

Checklist

• I have searched existing issues to ensure this is not a duplicate
• I have provided a clear description of the feature
• I have explained why this feature would be useful</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature]: User Guide #48

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Malcolmnixon]

@copilot So it turns out the ENTIRE user guide is under section 1 (one primary-heading) - consider dropping critical sections down to primary-headings.

[Copilot]

@copilot So it turns out the ENTIRE user guide is under section 1 (one primary-heading) - consider dropping critical sections down to primary-headings.

Done! Restructured the guide to use primary headings for all major sections (Introduction, Installation, Getting Started, Command-Line Options, Common Use Cases, Report Format, Running Self-Validation, Best Practices, Troubleshooting, and Additional Resources). All subsections were shifted down one level to maintain proper hierarchy. Commit: e55eccb