QualCoder v2 Documentation Updater

Quick Reference

Documentation Structure

Doc-to-Feature Mapping

Workflow

Step 1: Verify Tests Pass

# Run all E2E tests
QT_QPA_PLATFORM=offscreen make test-all

# Check Allure report
allure serve allure-results/

# List tested features
grep -rh "@allure.story.*QC-" src/tests/e2e/*.py | sort -u

Step 2: Capture Screenshots

Use the DocScreenshot utility in E2E tests:

from src.tests.e2e.utils.doc_screenshot import DocScreenshot

class TestCreateCodeDialog:
    def test_dialog_appearance(self, coding_screen):
        # Open dialog
        coding_screen._on_new_code_shortcut()
        dialog = coding_screen._current_dialog

        # Capture for docs
        DocScreenshot.capture(dialog, "create-code-dialog")

        dialog.close()

Naming Convention:

• •{feature}-{state}.png
• •Examples: create-code-dialog.png, coding-screen-with-codes.png

Step 3: Update Documentation

For each passed test story, update the corresponding doc:

1. •Check screenshot references - ensure images exist
2. •Update feature description - match tested behavior
3. •Add keyboard shortcuts - from E2E test assertions
4. •Update workflow diagrams - if flow changed

Step 4: Documentation Checklist

Before marking docs complete:

• • All referenced images exist in docs/user-manual/images/
• • Image captions describe what user sees
• • Keyboard shortcuts match actual implementation
• • Workflow matches E2E test steps
• • Links to related pages work

Screenshot Capture Utility

The DocScreenshot class provides consistent screenshot capture:

from src.tests.e2e.utils.doc_screenshot import DocScreenshot

# Basic capture
DocScreenshot.capture(widget, "feature-name")

# Capture with Allure attachment
DocScreenshot.capture(widget, "feature-name", attach_to_allure=True)

# Capture only if image doesn't exist (avoid overwriting)
DocScreenshot.capture_if_missing(widget, "feature-name")

Screenshot Guidelines

Missing Documentation Detection

Find untested features

# Get all tested features
grep -rh "@allure.story" src/tests/e2e/*.py | \
  sed 's/.*"\(QC-[0-9]*\.[0-9]*\).*/\1/' | sort -u

# Compare with DOC_COVERAGE.md
cat docs/DOC_COVERAGE.md | grep "QC-" | awk '{print $2}'

Find missing images

# Check all image references in docs
for doc in docs/user-manual/*.md; do
  echo "=== $doc ==="
  grep -o 'images/[^)]*' "$doc" | while read img; do
    [ ! -f "docs/user-manual/$img" ] && echo "MISSING: $img"
  done
done

Automated check script

# Run from project root
make docs-check

Update Workflow

After tests pass

1. •

   Check coverage matrix

   bash

   cat docs/DOC_COVERAGE.md
   

2. •

   Identify docs to update

   • •Look at which QC-XXX tests passed
   • •Find corresponding doc page in mapping
3. •

   Update documentation

   bash

   # Edit the relevant doc
   vim docs/user-manual/coding.md
   

4. •

   Verify images

   bash

   # Check referenced images exist
   grep -o 'images/[^)]*' docs/user-manual/coding.md | \
     xargs -I {} test -f "docs/user-manual/{}" || echo "Missing: {}"
   

5. •

   Update coverage matrix

   bash

   vim docs/DOC_COVERAGE.md
   # Mark feature as documented
   

6. •

   Commit changes

   bash

   git add docs/
   git commit -m "docs(user-manual): update after QC-XXX tests pass"
   

Integration with Definition of Done

From CLAUDE.md, documentation is required for Definition of Done:

1. •User documentation updated in docs/user-manual/
2. •API documentation updated in docs/api/ for MCP tools

Checklist per feature

• • E2E test passes with @allure.story("QC-XXX.YY")
• • Screenshots captured during test run
• • User manual page updated
• • API docs updated (if MCP tool)
• • DOC_COVERAGE.md updated
• • All image references valid

Quick Commands

# Capture all screenshots (re-run screenshot tests)
QT_QPA_PLATFORM=offscreen uv run pytest src/tests/e2e/ -k "capture" -v

# Check doc coverage
make docs-check

# Serve docs locally (if using mkdocs)
mkdocs serve

# Build docs
mkdocs build

Troubleshooting

Screenshots look different on CI

• •Use QT_QPA_PLATFORM=offscreen for consistent rendering
• •Set fixed widget sizes before capture
• •Use QApplication.processEvents() before grabbing

Image too large

# Scale down for docs
pixmap = widget.grab()
scaled = pixmap.scaled(800, 600, Qt.KeepAspectRatio, Qt.SmoothTransformation)
scaled.save(path)

Dark mode issues

• •Capture in both light and dark mode if needed
• •Name: feature-light.png, feature-dark.png