[CI] Update API docs for OpenZeppelin/openzeppelin-contracts v5.7.0-rc.0

[github-actions]

API Documentation Update

This Pull Request updates the API documentation.

Source Information

• Repository: OpenZeppelin/openzeppelin-contracts
• Reference: v5.7.0-rc.0
• Trigger Type: tag
• Output Directory: content/contracts/5.x/api
• Timestamp: 2026-07-15 16:29:06 UTC

Auto-generated via workflow_dispatch

[netlify]

✅ Deploy Preview for openzeppelin-docs-v2 ready!

Name	Link
🔨 Latest commit	5f6e1ed
🔍 Latest deploy log	https://app.netlify.com/projects/openzeppelin-docs-v2/deploys/6a57f0547e601100087d4e0f
😎 Deploy Preview	https://deploy-preview-206--openzeppelin-docs-v2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[ernestognw]

Review of the auto-generated v5.7.0-rc.0 docs

Ran a regression pass on this PR and applied the fixes directly on the branch (commit ad3d601 and c5763f8). Also opened a companion upstream PR on the contracts repo so the next regen picks up the source-side fixes automatically.

Direct MDX patches

Seven categories of regression the docgen pipeline introduces per run:

• Broken Solidity code block — extending-contracts.mdx — downdoc mangled a ```solidity block inside the .adoc, dedenting super.revokeRole(...) and dropping the function's closing }. Restored indentation and comments to match the upstream .adoc source.
• NatSpec {Type} leaks in prose — the resolver's "last hyphenated segment equals key" heuristic matched primitive types and external interface names against unrelated composite anchors, producing bare #Contract-something-Type fragments in prose. Fixed two occurrences: {ICompoundTimelock} in api/governance.mdx and {bytes32} in api/token/ERC20.mdx. Both rewritten to plain `Type` inline code.
• Cross-contract method mis-linking — BridgeFungible and BridgeNonFungible sections in api/crosschain.mdx had their _onSend/_onReceive bullets pointing at BridgeERC1155's array-typed variants (the resolver picked the first same-page match, ignoring which contract was being rendered). Repointed to the correct same-contract anchors.
• Dangling struct anchors + missing struct docs — RateLimiter.RefillingBucketItem, RateLimiter.RefillingBucket, RateLimiter.SlidingWindow, MerkleTree.Bytes32PushTree, and WebAuthn.WebAuthnAuth were linked from prose with no matching <a id> because contract.hbs didn't render structs. Added a proper Structs section to the template (see below) and rendered the affected structs directly in the current MDX so the PR is complete without waiting for a regen.
• Trailing === in heading — RateLimiter NatSpec used symmetric AsciiDoc setext (=== Limiter vs. entries ===) which is not the codebase convention. Stripped in api/utils.mdx. Upstream fix in openzeppelin-contracts#6612.
• [TIP]==== admonition dumped as prose — a block admonition in paymasters.adoc reached the MDX as bare paragraphs because the convert-adoc regex's emoji character class was missing 💡. Wrapped the content in <Callout> in paymasters.mdx and extended the regex (see transformer changes below).
• External Defender URL rewritten to a broken internal path — two Defender Proposals links in content/contracts/5.x/governance.mdx pointed at /defender/module/actions#transaction-proposals-reference; the anchor doesn't exist on that page. Repointed to /defender/module/transaction-proposals. Upstream fix in openzeppelin-contracts#6612.

Also: accounts.mdx had a legacy <script async> + <oz-wizard> embed; swapped for the <OZWizard /> component (c5763f8).

Docgen template additions (docgen/templates-md/)

Kept minimal — only what's needed to render new content the templates couldn't reach:

• contract.hbs — new Structs section: summary list of a contract's structs plus per-struct detail block (anchor, name, NatSpec, Solidity struct declaration). Same styling as the existing Modifiers/Functions/Events/Errors blocks. Fixes the dangling-struct-anchor pattern at the source: {RateLimiter.SlidingWindow} refs now resolve to a real <a id="RateLimiter-SlidingWindow"> with real content.
• properties.js — new structs property (returns StructDefinition nodes from the current contract).
• helpers.js — two new helpers: struct-dev extracts the @dev body from a struct's raw NatSpec documentation; struct-member-decl renders a member as <type> <name> for the Solidity code block. Nothing else — no defensive guards, no primitive-type filters, no current-contract scoping. Design principle: keep the transformer minimal; upstream authoring mistakes get fixed upstream.

Transformer patches (scripts/convert-adoc.js)

Both are genuine transformer bugs, not upstream masking:

• Preprocess ```lang fenced blocks to [source,lang]\n----\n...\n---- form before running downdoc. Prevents downdoc from mangling the code contents (fixes the code-block regression at the transformer level).
• Add 💡 to the <dl> emoji character class for <Callout> conversion so [TIP]==== blocks emitted by downdoc as <dl><dt><strong>💡 TIP</strong>... are wrapped correctly.

Upstream PR

openzeppelin-contracts#6612 fixes:

• The two Defender Proposals xrefs in docs/modules/ROOT/pages/governance.adoc — from xref:defender::module/actions.adoc#transaction-proposals-reference to xref:defender::module/transaction-proposals.adoc.
• The symmetric === setext heading in contracts/utils/RateLimiter.sol NatSpec.

Approach going forward

The design principle is: the transformer stays minimal. It should not paper over upstream NatSpec / .adoc authoring mistakes with defensive code — those become invisible failure modes that mask the same class of bug on every future generation. Every regression pattern surfaced by a regen gets either an upstream source fix (so the next regen produces correct output) or a direct MDX patch on the current PR, or both. A skill draft is available (add-docgen-fixup-skill branch — not yet merged) that catalogs the seven patterns above with symptom / detection / root cause / upstream fix / MDX patch, and provides a repeatable review workflow for the next regen.

[luiz-lvj]

lgtm