chore: added markdown docs templates

[stevedylandev]

This PR adds the updated templates-md and config-md.js to the docs directory. By doing this we can generate API documentation for OpenZeppelin/docs remotely. Please see the guide here

Summary by CodeRabbit

• Documentation
  • Updated documentation generation system to use markdown-based templates with enhanced rendering for Solidity contracts, improving organization and cross-referencing capabilities.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "chore: added markdown docs templates" accurately describes the main objective of this changeset. The PR adds a new markdown documentation template system with several new files (contract.hbs, page.hbs, helpers.js, properties.js, and config-md.js) to enable API documentation generation. The title is specific and clearly communicates the primary change—adding markdown documentation templates—in a concise manner that a teammate scanning the commit history would immediately understand. The title is neither vague nor misleading and directly reflects the content of the changeset.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 6

♻️ Duplicate comments (1)

docs/templates-md/properties.js (1)

23-29: Code duplication and null safety issue.

This code duplicates the signature-building logic from the anchor function and has the same null safety concerns.

See the refactor suggestion in the previous comment (lines 10-16) which addresses both issues by extracting common logic and adding null checks.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3b358b3 and f41f1b0.

📒 Files selected for processing (6)

• docs/config-md.js (1 hunks)
• docs/templates-md/contract.hbs (1 hunks)
• docs/templates-md/helpers.js (1 hunks)
• docs/templates-md/page.hbs (1 hunks)
• docs/templates-md/properties.js (1 hunks)
• hardhat.config.js (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

hardhat.config.js (2)

docs/templates-md/helpers.js (2)

• require (1-1)
• require (4-4)

docs/templates-md/properties.js (2)

• require (1-1)
• require (2-2)

docs/templates-md/properties.js (1)

docs/templates-md/helpers.js (2)

• slug (67-72)
• i (139-139)

docs/templates-md/helpers.js (1)

docs/templates-md/properties.js (5)

• require (1-1)
• require (2-2)
• item (83-83)
• signature (11-11)
• signature (24-24)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: slither
• GitHub Check: tests-foundry
• GitHub Check: coverage
• GitHub Check: tests

🔇 Additional comments (3)

docs/templates-md/properties.js (3)

59-65: LGTM! Good defensive coding.

The ternary operator properly handles the case where item.variables doesn't exist, preventing potential runtime errors.

---

67-72: LGTM!

The function correctly aggregates publicly visible functions and public variables using AST queries with appropriate visibility filters.

---

47-57: Add null safety checks for item.inheritance.

All three functions assume item.inheritance exists and is an array. If it's undefined, calling .some() will throw a runtime error.

Apply this diff to add defensive checks:

 module.exports['has-functions'] = function ({ item }) {
-  return item.inheritance && item.inheritance.some(c => c.functions.length > 0);
+  return item.inheritance?.some(c => c.functions?.length > 0) ?? false;
 };
 
 module.exports['has-events'] = function ({ item }) {
-  return item.inheritance && item.inheritance.some(c => c.events.length > 0);
+  return item.inheritance?.some(c => c.events?.length > 0) ?? false;
 };
 
 module.exports['has-errors'] = function ({ item }) {
-  return item.inheritance && item.inheritance.some(c => c.errors.length > 0);
+  return item.inheritance?.some(c => c.errors?.length > 0) ?? false;
 };

Likely an incorrect or invalid review comment.

[stevedylandev]

Updated the following legacy patterns in the natspec:

• https://url[Link Text] -> [Link Text](https://url)
• WARNING: | IMPORTANT: | CAUTION: | IMPORTANT: -> <Callout type=warn"></Callout>
• NOTE: | TIP: ->
• Delimitters such as ==== -> #### or removed if no header text
  present

With the adoc conversion to mdx in addition to these changes to the natspec we were able to simplify docs/helpers.js. While it is still a fair bit larger than the original version, much of this was necessary to make docgen work with markdown syntax and keeping cross reference links.

[james-toussaint]

So most replacing logic can be removed now right?

[stevedylandev]

I think for this repo we could remove pieces like L:146-149 and maybe L:157-162, but these are patterns used in other libraries. We definitely still need L:151-155 and the rest of functions to handle instances where a contract references another contract, .e.g. you might have {ERC20} inside ERC1155 comments and we need to turn that into a markdown link.

[james-toussaint]

I suggest to:

1. Rename that workflow file to docs.yml
2. Add a temporary manual dispatch in order to test here (which can be removed before merging)