fix: update docgen templates and automate API reference generation#140
Draft
fix: update docgen templates and automate API reference generation#140
Conversation
…t fixes
- Remove fuzzy reference matching that caused cross-standard contamination
(e.g., ERC20 constructor referencing Governor.name, IERC6909Metadata.symbol)
- Add same-page preference so {name} on an ERC20 page resolves to ERC20.name
- Use absolute paths for cross-page links via API_DOCS_PATH
- Fix multi-line callout handling (NOTE: blocks spanning multiple lines)
- Escape bare < in natspec (e.g., < 0x80) to prevent MDX parse errors
- Convert Antora xref patterns to markdown links
- Convert AsciiDoc headings (====) to markdown (####)
- Clean up orphaned block delimiters
- Strip /index from links for Fumadocs compatibility
Regenerated from openzeppelin-contracts (master) and openzeppelin-community-contracts (master) using updated docgen templates. - All cross-page links use absolute paths - No cross-standard contamination in reference resolution - No legacy AsciiDoc patterns in output - 0 link validation errors
Wrap inherited function/event/error listings in <details>/<summary> toggles so the contract's own items are prominent and inherited items are accessible but not overwhelming. Only renders toggles for inherited contracts that have items for that section (no empty toggles). Also regenerates API reference output with updated template.
The script now injects canonical MDX templates from docgen/templates-md/ into the cloned source repo before running docgen. This means source repos don't need to have MDX templates committed — the docs monorepo is the single source of truth. - Copies templates-md/ and config-md.js into cloned repo - Customizes API_DOCS_PATH, GitHub link, and import path per source repo - Patches hardhat config to use config-md - Overwrites config.js so prepare-docs.sh scripts still work - Handles local paths, broken symlinks, both .js and .ts hardhat configs - Adds --skip-template-inject flag for repos that already have MDX templates
Regenerated via generate-api-docs.js with template injection for: - openzeppelin-contracts (master) -> content/contracts/5.x/api/ - openzeppelin-community-contracts (master) -> content/community-contracts/api/ - openzeppelin-confidential-contracts (master) -> content/confidential-contracts/api/ All repos: 0 link errors, clean build.
New GitHub Actions receiver workflows for API doc generation: - generate-api-docs-contracts.yml: versioned paths (5.x/api), tag-based - generate-api-docs-confidential-contracts.yml: non-versioned (api/), tag-based Both include link validation step before PR creation.
Adds postinstall + lint:links step before PR creation to catch broken links in generated docs before they're merged.
Prevents temp directories from showing in source control if a generate-api-docs.js run is interrupted before cleanup.
For repos using Move, Rust, Cairo, or other languages that generate MDX through their own tooling, the script can now skip template injection and docgen entirely and just copy pre-generated MDX files. Usage: node generate-api-docs.js --repo <url> --api-output <dir> --pre-generated <path> This keeps the workflow generator-agnostic: Solidity repos use the default injection mode, other repos use --pre-generated.
✅ Deploy Preview for openzeppelin-docs-v2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Replace the old manual template-copy instructions with documentation for the template injection approach and automated GitHub workflow. Covers Solidity repos, non-Solidity repos (--pre-generated flag), canonical template locations, and versioning strategy.
- Use execFileSync for git clone to prevent command injection from CLI arguments (array args instead of shell string interpolation) - Add explicit permissions block to all receiver workflows to limit GITHUB_TOKEN scope to contents:write and pull-requests:write
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Details
Template fixes (docgen/templates-md/helpers.js)
The previous helpers.js used fuzzy matching for natspec references, which caused cross-standard contamination. For example, the ERC20 constructor description referenced Governor.name and IERC6909Metadata.symbol instead of ERC20.name and ERC20.symbol.
Fixes include:
<escaping in natspec to prevent MDX parse errorsCollapsible inherited functions (docgen/templates-md/contract.hbs)
Inherited function/event/error listings in TOC sections are now wrapped in collapsible toggles. The contract's own items are visible by default; inherited items are accessible but not overwhelming. Empty toggles are filtered out.
Template injection (scripts/generate-api-docs.js)
The script now injects canonical MDX templates from docgen/templates-md/ into the cloned source repo before running docgen. This makes the docs monorepo the single source of truth for templates. Source repos do not need MDX templates committed.
The script also supports a --pre-generated flag for non-Solidity repos that generate MDX through their own tooling.
Receiver workflows
New workflows for openzeppelin-contracts (versioned, tag-based) and confidential-contracts (non-versioned, tag-based). Link validation step added to all receiver workflows including the existing community-contracts workflow.
Test plan
pnpm run check(0 errors)pnpm run build(clean)