docs(reference): milestone 8 phase 1 - API reference toolchain wired into CI - #47
Conversation
…into CI DefaultDocumentation wins the ADR-0032 bake-off (xmldocmd's host build doesn't support net10.0 assemblies, hard-fails on load). Wires it into a new generate-api-reference.sh + api-reference.yaml drift-detection gate, core-package-first so integration packages' cross-package <see cref>s resolve locally instead of DotnetApiFactory's fabricated learn.microsoft.com fallback, plus a post-processing fix for '#ctor' filenames (the raw CLR ctor metadata name collides with the URL fragment delimiter). Verified with a real mkdocs build, not just the generated Markdown. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 37ba63960b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…s and stale ctor anchors Codex review found the #ctor filename rename left same-page anchor names carrying a stale "ctor.md#" prefix that no longer matches the (already- fixed) href fragment, and that DotnetApiFactory's BCL-fallback behavior produces dead learn.microsoft.com links whenever a public member's XML docs <see cref> an internal Compono type (38 occurrences, not the single instance originally noted). Both fixed in the generation script's post-processing pass; regenerated and reverified with a real mkdocs build. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ce4849f574
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…eview) A member's own <paramref>/<typeparamref> self-reference always links back to its containing type's page, but the anchor lives wherever OverloadsGenerator actually placed that overload once a member has more than one. Confirmed general (92 mismatched fragment links across all four packages, not just the flagged constructor case) rather than patched narrowly: builds an anchor-id -> actual-file map per package directory and rewrites any same-package link pointing at the wrong file. 0 mismatches after the fix; reverified with a real mkdocs build and full test suite. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: eddf5d3c38
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…gus-link fix Two changes, both from PR #47 review/follow-up: 1. Delete the standalone api-reference.yaml workflow and move its regenerate-and-diff-check steps into docs.yml's own build job, sequentially before mkdocs build. The two workflows previously had no ordering relationship (no needs/workflow_run), so a failing drift check could never actually stop a bad deploy - per user direction, not a silent choice (the local-generation-only alternative would reverse ADR-0032's explicit CI-catches-drift requirement without an amendment). 2. Generalize the bogus-fallback-link fix from a compono.* blocklist to a system.*/microsoft.* allowlist, catching third-party dependency types (Bogus.Faker, NSubstitute.Substitute.For, Xunit.v3.IDataAttribute) that DotnetApiFactory fabricates the same dead-link fallback for. Also fixes a link-text parsing bug in that same regex: [^\]]+ stops at the first literal ']', silently failing to match a signature whose display text contains escaped array-parameter brackets. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
compono/.github/workflows/docs.yml
Line 110 in 20236e9
Make MkDocs warnings fail the docs job
ADR-0032 requires CI to fail on broken internal links, but this workflow still runs mkdocs build --clean without --strict and mkdocs.yml does not enable strict validation; the MkDocs CLI docs state that strict mode aborts the build on warnings. When a generated or handwritten API page introduces a broken internal link, MkDocs will warn but this job will continue to upload/deploy the site, so the new gate does not actually enforce the link-failure criterion.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
#47 review) docs.yml ran mkdocs build with no --strict, so ADR-0032's own "CI fails on broken internal links" requirement was never actually enforced - a warning never fails a plain mkdocs build. Enabling --strict surfaced exactly the 4 pre-existing broken links already visible as noise throughout this PR's verification: ADR-0014/0015/0016/0022 each link to .claude/skills/engineering-workflow/references/design-decisions.md, which sits outside docs_dir entirely and can never resolve in the built site regardless of relative-path depth. Converted those 4 references from a dead hyperlink to plain, unlinked text - link syntax only, the ADRs' Decision/Rationale/Consequences prose is untouched, per this repo's own ADR-immutability rule. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Re: #47 (review) — Fixed in 2ff6748. You're right that Enabling Verified: |
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2ff6748fbf
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
… review) Directory.Build.targets is auto-imported into every project the same way Directory.Build.props is (just after the project body instead of before), including the four publishable packages this job's drift-check step builds - but only Directory.Build.props was in the trigger paths lists. A PR touching only Directory.Build.targets would silently skip both the drift check and the site rebuild. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 75982d4612
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Two spots hadn't been updated when reference/api went from skeleton to real, generated content: documentation-architecture.md's top-level intro still said reference/api didn't exist yet pending a toolchain decision, contradicting its own Section 11 status a few pages down; PLAN-0008 Phase 1's mkdocs verification note still recorded the earlier non-strict run with four warnings, contradicting the --strict fix recorded later in the same Notes section. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Summary
Executes ADR-0032 / PLAN-0008 Phase 1: evaluates and wires the
docs/reference/api/generation toolchain.DefaultDocumentation(1.2.5) vsxmldocmd(2.9.0), against all four publishable packages' real net10.0 assemblies.xmldocmdeliminated outright — its host build only targets net6.0/net7.0 and throwsFileNotFoundExceptionloadingSystem.Runtimefor a net10.0 target assembly.DefaultDocumentationpassed every ADR-0032 criterion (generics, overloads, inheritance, exceptions, nullable signatures, deterministic output) and ships an active net10.0 host build.<see cref>(e.g.Compono.XunitV3→Compono.Composer) fell back to a fabricatedlearn.microsoft.comURL. Fixed by generatingComponocore first with--LinksOutputFilePath, feeding it to the three integration packages'--ExternLinksFilePaths.#ctormetadata name —#is the URL fragment delimiter, breaking MkDocs routing (caught by a realmkdocs build, not just eyeballing Markdown). Post-processed to.ctorin the generation script..github/scripts/generate-api-reference.sh+.github/workflows/api-reference.yamldrift-detection CI gate (regeneration must produce no uncommitted diff). Missing-XML-doc-comment enforcement already exists via Phase 0'sCS1591gate —DefaultDocumentationhas no independent detection to add on top of it.docs/reference/index.mdandmkdocs.ymlnav updated to surface the new API Reference section.Test plan
dotnet build/dotnet test— full solution, 854/854 tests pass (no C# source touched by this phase).docs/reference/api/from scratch twice — byte-identical output (deterministic).uv run mkdocs build --cleanagainst the full site — builds clean; only pre-existing, unrelated warnings (broken.claude/skills/.agents/skillslinks from earlier ADR pages).🤖 Generated with Claude Code