[mkarlesky]

This is the last of three stacked PRs that move the user documentation onto https://docs.throwtheswitch.org/vscode-ceedling/. It stacks on #40 and adds the How-To section: nine scenario guides, its card landing page, and the Help page. Every block a reader pastes from a guide is checked by a test.

Guides

• Start Testing in Your Project: the first run, and what to do when no tests appear.
• Debug a Test: launch.json per OS in linked tabs: Linux gdb, macOS CodeLLDB or cppdbg with lldb, and Windows MSYS2 gdb. Also two projects, and a custom :build_root.
• Measure Code Coverage: gcovr and ReportGenerator tabs with their installs and mixins. Also sources above the project, accumulating counters, and :report_task.
• See Compiler Errors in the Editor:
  • the gcc preset, which covers GCC, Clang and GNU ld;
  • adding GCC's notes, which means restating the preset, since patterns replaces it;
  • IAR's documented format;
  • writing your own pattern.
• Work With Several Projects: a project in a subdirectory, several projects in one folder with mixin precedence, multi-root workspaces, project files of your own, and a same-named test files table by Ceedling version.
• Run the Ceedling You Use: shellPath for MSYS2 and Git Bash, with how to test the way the extension runs commands. Also Bundler, vendor/ceedling, and WHICH_CEEDLING or :which_ceedling with launcher limits.
• Upgrade Ceedling: refreshing, and the 1.2.2 clobber.
• Write Parametrized Tests: TEST_CASE, TEST_RANGE and TEST_MATRIX, with their case labels.
• Find a Crashing Test: :use_backtrace choices :simple, :gdb and :none.
• Help: cards for bug reports, the forum, Ceedling Assist and contributing, plus the sponsorship box.

🐛 Fix found while documenting

A crashed test's gdb log, with :use_backtrace: :gdb on Ceedling 1.1.0 and later, never became a link in its failure message, in 2.0.1 too. The run's transcript followed the log reference, so the end-anchored match failed. The reference is now found where it ends Ceedling's own message. This is test-first, with a reverting mutation check, and has a CHANGELOG entry.

Tests

• tests/unit/docsExamples.test.ts reads each guide's fences line by line. A fence it can't read fails, as does any block other than sh or c without an <!-- example: <kind> <name> --> marker.
  • settings and workspace examples are checked recursively against package.json's schema: type, enum, required fields and unknown fields. A setting name with the wrong case fails.
  • A launch example must use the debug token. A mixin must be Ceedling YAML.
  • A patterns example must find exactly the expected problems, on every field, in real Ceedling 1.2.2 compile and link output captured for this PR, or in IAR's documented form. No IAR compiler was available to capture.
  • The notes example must restate the gcc preset exactly, which normalizePatterns checks.
• problemMatching.test.ts checks that the gcc preset reads a Clang 19.1 capture.
• Mutation checks. Each of these fails the tests:
  • drift between the restated preset and the code;
  • a wrong group;
  • a wrong column;
  • an unknown setting, or a setting name with the wrong case;
  • an enum typo;
  • a wrong field type;
  • a missing token;
  • an unmarked block;
  • an unreadable fence.

Verification

• just test passes (636 unit, 20 integration). just lint is clean. just docs-build --strict passes.
• Three reviewers ran a defensive review: guide accuracy against the code, Ceedling facts against Ceedling's source at v1.2.2, and tests, fixtures and prose. Fixed:
  • Code: the gdb link bug.
  • Ceedling facts:
    • :simple is Ceedling's default and reruns every case;
    • :none fails every test;
    • Ceedling shows a tool's output only when the tool fails, so problem matching sees no warnings from a compile that succeeds;
    • :build_root has no built-in default;
    • an older launcher gives no warning for :which_ceedling;
    • the shell check must use bash -c, as the extension does;
    • CodeLLDB bundles lldb.
  • The example tests' false passes that the reviewers found.
  • Rendering: stray <p> wrapping around tabbed code blocks.
  • Prose: assorted fixes.

Known

• macOS CI: the job hasn't run on Docs site 1/3: MkDocs, Material, and mike tooling #39 or Docs site 2/3: the User Manual and a slimmed README #40. GitHub never assigned a macOS runner, citing capacity limits, and the job timed out in the queue. Ubuntu, Windows and docs pass.
• Help page link: it links docs/Architecture.md on master, which exists there only after next_version merges. The site first deploys at that release.

🤖 Generated with Claude Code