Removes docs directory #263
Conversation
andrew-fleming
left a comment
andrew-fleming
left a comment
There was a problem hiding this comment.
Looks good! We still have the old site that's connected: https://old-docs.openzeppelin.com/contracts-compact/0.0.1/ . I think we should create a docs branch then update the playbook on the old docs repo here like this:
- url: https://github.com/OpenZeppelin/compact-contracts
branches:
- docs-v*
start_path: docs
so it can fetch the last prerelease (as opposed to reading from HEAD as it is now). WDYT?
Also, I think we can remove the docs tasks in turbo.json. I just left a question and a small suggestion. Lastly, I'd create an issue since it's not a trivial change so we can track it in the project :)
| The online version of the Compact contracts documentation is maintained at [OpenZeppelin/docs](https://github.com/OpenZeppelin/docs). | ||
| It should mirror all documentation embedded within the contracts themselves with additional context and usage examples if applicable. | ||
| Pull requests in [OpenZeppelin/docs](https://github.com/OpenZeppelin/docs) should be linked to the corresponding pull request in this repo. | ||
|
|
There was a problem hiding this comment.
Sooooooooooooo this adds a ton of friction for contributors. It's a good idea to have some coordination with linking a PR from the docs repo as you mentioned; however, this feels messy. The consequences of centralization :(
I was considering if we could place the docs repo in a submodule or subtree so all changes are, from the contributor's perspective, from the same project. The former is a bit more convenient for the contributor but they need to know how to work with submodules. The latter adds complexity to us but improves dx for the contributor...or keep it as-is. Thoughts?
There was a problem hiding this comment.
Totally agree, I think we can make this easier on contributors by using Git subtrees. I can add some scripts and more info to CONTRIBUTING.md to standardize the workflow.
package.json
Outdated
| "scripts": { | ||
| "docs": "turbo run docs --filter=docs", | ||
| "docs:watch": "turbo run docs:watch --filter=docs", | ||
| "compact": "turbo run compact --filter=@openzeppelin-compact/contracts --log-prefix=none", | ||
| "build": "turbo run build --filter=!'docs' --log-prefix=none", |
There was a problem hiding this comment.
We can remove --filter=!'docs' in build
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughThe pull request deprecates the embedded documentation directory by removing all module documentation pages, API references, Antora configuration, and documentation build scripts. Documentation content is being migrated to an external repository, and references in root-level configuration files are updated accordingly. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
GUIDELINES.md (1)
30-32: Add comma for clarity.Line 31 would read more clearly with a comma before the prepositional phrase.
Apply this diff:
- It should mirror all documentation embedded within the contracts themselves with additional context and usage examples if applicable. + It should mirror all documentation embedded within the contracts themselves, with additional context and usage examples if applicable.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
yarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (22)
.github/PULL_REQUEST_TEMPLATE.md(1 hunks)CONTRIBUTING.md(1 hunks)GUIDELINES.md(1 hunks)docs/antora.yml(0 hunks)docs/modules/ROOT/nav.adoc(0 hunks)docs/modules/ROOT/pages/access.adoc(0 hunks)docs/modules/ROOT/pages/api/access.adoc(0 hunks)docs/modules/ROOT/pages/api/fungibleToken.adoc(0 hunks)docs/modules/ROOT/pages/api/multitoken.adoc(0 hunks)docs/modules/ROOT/pages/api/nonFungibleToken.adoc(0 hunks)docs/modules/ROOT/pages/api/security.adoc(0 hunks)docs/modules/ROOT/pages/api/utils.adoc(0 hunks)docs/modules/ROOT/pages/extensibility.adoc(0 hunks)docs/modules/ROOT/pages/fungibleToken.adoc(0 hunks)docs/modules/ROOT/pages/index.adoc(0 hunks)docs/modules/ROOT/pages/multitoken.adoc(0 hunks)docs/modules/ROOT/pages/nonFungibleToken.adoc(0 hunks)docs/modules/ROOT/pages/security.adoc(0 hunks)docs/modules/ROOT/pages/utils.adoc(0 hunks)docs/modules/ROOT/pages/zkCircuits101.adoc(0 hunks)docs/package.json(0 hunks)package.json(0 hunks)
💤 Files with no reviewable changes (19)
- docs/modules/ROOT/nav.adoc
- docs/modules/ROOT/pages/access.adoc
- docs/modules/ROOT/pages/multitoken.adoc
- docs/modules/ROOT/pages/api/nonFungibleToken.adoc
- docs/modules/ROOT/pages/security.adoc
- docs/modules/ROOT/pages/index.adoc
- docs/modules/ROOT/pages/api/security.adoc
- docs/modules/ROOT/pages/utils.adoc
- docs/antora.yml
- package.json
- docs/modules/ROOT/pages/zkCircuits101.adoc
- docs/modules/ROOT/pages/api/access.adoc
- docs/package.json
- docs/modules/ROOT/pages/fungibleToken.adoc
- docs/modules/ROOT/pages/extensibility.adoc
- docs/modules/ROOT/pages/nonFungibleToken.adoc
- docs/modules/ROOT/pages/api/utils.adoc
- docs/modules/ROOT/pages/api/fungibleToken.adoc
- docs/modules/ROOT/pages/api/multitoken.adoc
🧰 Additional context used
🪛 LanguageTool
GUIDELINES.md
[uncategorized] ~31-~31: Possible missing comma found.
Context: ...mentation embedded within the contracts themselves with additional context and usage examp...
(AI_HYDRA_LEO_MISSING_COMMA)
⏰ 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). (2)
- GitHub Check: Run Test Suite
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (2)
CONTRIBUTING.md (1)
91-91: LGTM.Minor formatting correction improves consistency.
.github/PULL_REQUEST_TEMPLATE.md (1)
27-29: LGTM.PR checklist links are correctly updated to reference the new guidance sections in GUIDELINES.md. All anchor links are valid and will guide contributors appropriately.
andrew-fleming
left a comment
andrew-fleming
left a comment
There was a problem hiding this comment.
Hey @emnul I see we have the docs branch 👍
we just need to remove the --filter=!'docs', right?
|
Currently blocked by OpenZeppelin/docs.openzeppelin.com#458 |
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
|
|
||
| // Handle multi-line callouts | ||
| content = content.replace( | ||
| /^(TIP|NOTE):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, |
Check failure
Code scanning / CodeQL
Inefficient regular expression High documentation
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI about 9 hours ago
To fix the inefficient regular expression, we should remove the ambiguous use of .* inside a repetition. Instead of matching "any character (possibly none), followed optionally by a \n, repeated non-greedily," we should instead use a pattern that matches any line except a blank line, corresponding to how AsciiDoc callouts work: callout paragraphs end after a double newline (\n\n) or EOF. This can be done by capturing all lines until a blank line (or EOF) appears, using a sequence that consumes full lines but does not allow blank lines. Specifically, replace the ((?:.*\n?)*?) portion with a more precise pattern such as ((?:[^\n].*(?:\n|$))*), which matches lines that are not blank. The lookahead remains unchanged to halt at a blank line or EOF. This update needs to be applied both to the TIP/NOTE and IMPORTANT|WARNING|CAUTION multi-line callout cases in the script.
Only the regular expressions in the content.replace() calls at lines 52 and 57 within docs/scripts/convert-adoc.js need to be changed.
| @@ -49,12 +49,12 @@ | ||
|
|
||
| // Handle multi-line callouts | ||
| content = content.replace( | ||
| /^(TIP|NOTE):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, | ||
| /^(TIP|NOTE):\s*\n((?:[^\n].*(?:\n|$))*)(?=\n\n|$)/gm, | ||
| "<Callout>\n$2\n</Callout>", | ||
| ); | ||
|
|
||
| content = content.replace( | ||
| /^(IMPORTANT|WARNING|CAUTION):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, | ||
| /^(IMPORTANT|WARNING|CAUTION):\s*\n((?:[^\n].*(?:\n|$))*)(?=\n\n|$)/gm, | ||
| "<Callout type='warn'>\n$2\n</Callout>", | ||
| ); | ||
| // Write preprocessed content |
| ); | ||
|
|
||
| content = content.replace( | ||
| /^(IMPORTANT|WARNING|CAUTION):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, |
Check failure
Code scanning / CodeQL
Inefficient regular expression High documentation
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI about 9 hours ago
To fix the inefficient regular expression at line 57, we need to remove ambiguity in the repeated part (?:.*\n?)*?. The issue comes from using .* (which can match zero or more characters including newlines), typically inside a repetition that may match the same sequence in multiple ways. A standard way to fix this is to match lines more precisely, using patterns that cannot overlap. Since the intention seems to be to capture the body of a multi-line callout (after lines like IMPORTANT:\n, etc.) up to the next blank line or end of file, we can use a pattern such as:
((?:[^\n]*\n)*?)
Here, [^\n]*\n matches each line, and repeating this captures all lines until the lookahead assertion for double newline or end-of-string. This removes the ambiguity that exists in the original .*\n? pattern. The same fix applies to the similar regex at line 52.
Edit only lines 52 and 57 in docs/scripts/convert-adoc.js, replacing (?:.*\n?)*? with (?:[^\n]*\n)*?.
| @@ -49,12 +49,12 @@ | ||
|
|
||
| // Handle multi-line callouts | ||
| content = content.replace( | ||
| /^(TIP|NOTE):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, | ||
| /^(TIP|NOTE):\s*\n((?:[^\n]*\n)*?)(?=\n\n|$)/gm, | ||
| "<Callout>\n$2\n</Callout>", | ||
| ); | ||
|
|
||
| content = content.replace( | ||
| /^(IMPORTANT|WARNING|CAUTION):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, | ||
| /^(IMPORTANT|WARNING|CAUTION):\s*\n((?:[^\n]*\n)*?)(?=\n\n|$)/gm, | ||
| "<Callout type='warn'>\n$2\n</Callout>", | ||
| ); | ||
| // Write preprocessed content |
| .replace(/^\//, "^/") | ||
| .replace(/^(?!\^)/, "^.*"); | ||
|
|
||
| const regex = new RegExp(pattern); |
Check failure
Code scanning / CodeQL
Regular expression injection High documentation
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI about 9 hours ago
To fix the problem, we need to ensure that user input used in the construction of a regular expression is properly escaped, so that any metacharacters are treated as literals, except for the special glob *, which is intentionally converted into .*. The best standard method is to escape user input using _.escapeRegExp from lodash, or a local equivalent if dependencies are to be minimized.
- Specifically, on line 161 where
scopeis used to createpattern, first escape all regex metacharacters using an escape function, then convert escaped glob\*to.*, so that only the intended wildcard is interpreted as a regex wildcard. - Import
escapeRegExpfrom lodash (or implement a local equivalent if adding a dependency is undesirable). - Only apply
.replace(/\*/g, ".*")after escaping to make sure only*is interpreted as a wildcard. - Add the necessary import at the top of the file.
| @@ -4,6 +4,7 @@ | ||
| scanURLs, | ||
| validateFiles, | ||
| } from "next-validate-link"; | ||
| import escapeRegExp from "lodash.escaperegexp"; | ||
| import type { InferPageType } from "fumadocs-core/source"; | ||
| import { source } from "@/lib/source"; | ||
| import { writeFileSync } from "fs"; | ||
| @@ -158,8 +159,8 @@ | ||
| // Convert scope pattern to regex | ||
| // /contracts/* becomes ^/contracts/.* | ||
| // contracts/* becomes ^.*contracts/.* | ||
| const pattern = scope | ||
| .replace(/\*/g, ".*") | ||
| const pattern = escapeRegExp(scope) | ||
| .replace(/\\\*/g, ".*") // Replace the escaped '*' with '.*' to act as a glob | ||
| .replace(/^\//, "^/") | ||
| .replace(/^(?!\^)/, "^.*"); | ||
|
|
| @@ -52,7 +52,8 @@ | ||
| "remark-mdx": "^3.1.1", | ||
| "shiki": "^3.12.2", | ||
| "tailwind-merge": "^3.3.1", | ||
| "unist-util-visit": "^5.0.0" | ||
| "unist-util-visit": "^5.0.0", | ||
| "lodash.escaperegexp": "^4.1.2" | ||
| }, | ||
| "devDependencies": { | ||
| "@biomejs/biome": "^2.2.4", |
| Package | Version | Security advisories |
| lodash.escaperegexp (npm) | 4.1.2 | None |
|
|
||
| // Handle multi-line callouts | ||
| content = content.replace( | ||
| /^(TIP|NOTE):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, |
Check failure
Code scanning / CodeQL
Inefficient regular expression High documentation
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI about 9 hours ago
The problematic part is ((?:.*\n?)*?) which may cause exponential backtracking. The intent is to capture multiple lines after a callout start ("TIP:" or "NOTE:") up to a blank line or end of string.
To fix this, instead of using nested repetitions and ambiguous patterns, match each line individually using a non-greedy pattern that captures all lines until a double newline (\n\n) or end of string. This can be achieved reliably by matching one or more lines that do not themselves constitute a blank line.
Replace the original pattern:
/^(TIP|NOTE):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gmwith a safer one using:
/^(TIP|NOTE):\s*\n((?:[^\n].*\n?)*)/gmHere, [^\n].*\n? matches a line with at least one character, and the outer repetition collects all such lines; this avoids ambiguity in matching the repeated lines and prevents backtracking caused by .* with nested quantifiers. Optionally, to ensure we don't include blank lines, we can stop at a double newline using a lookahead, as in the original, but in a less ambiguous way:
/^(TIP|NOTE):\s*\n([\s\S]*?)(?=\n\n|$)/gmHere, [\s\S]*? is a common idiom in JavaScript regex for matching any character (including newlines) non-greedily, up to the next double newline or end of string. This is not ambiguous and avoids catastrophic backtracking. We'll use this form for maximum compatibility.
Only line 43 in docs/scripts/process-mdx.js needs to be changed; no imports or further changes are required.
| @@ -40,7 +40,7 @@ | ||
|
|
||
| // Handle multi-line callouts | ||
| content = content.replace( | ||
| /^(TIP|NOTE):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, | ||
| /^(TIP|NOTE):\s*\n([\s\S]*?)(?=\n\n|$)/gm, | ||
| "<Callout>\n$2\n</Callout>", | ||
| ); | ||
|
|
| ); | ||
|
|
||
| content = content.replace( | ||
| /^(IMPORTANT|WARNING|CAUTION):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, |
Check failure
Code scanning / CodeQL
Inefficient regular expression High documentation
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI about 9 hours ago
To fix the inefficiency, we should rewrite the problematic part: ((?:.*\n?)*?). The intent seems to be: "capture all content following an 'IMPORTANT', 'WARNING', or 'CAUTION' label and a newline, up to the next blank line or end of input."
Instead of using .*\n?, which can match newlines in ambiguous ways, we should match lines one-by-one: (?:[^\n]*\n?)*? matches non-newline characters followed optionally by a newline, and is unambiguous.
Thus, change (.*\n?)*? to ([^\n]*\n?)*? in both line 48 and the analogous case on line 43 (for TIP/NOTE).
Edit only the regex in the relevant content.replace calls. Nothing else needs to change.
| @@ -40,12 +40,12 @@ | ||
|
|
||
| // Handle multi-line callouts | ||
| content = content.replace( | ||
| /^(TIP|NOTE):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, | ||
| /^(TIP|NOTE):\s*\n((?:[^\n]*\n?)*?)(?=\n\n|$)/gm, | ||
| "<Callout>\n$2\n</Callout>", | ||
| ); | ||
|
|
||
| content = content.replace( | ||
| /^(IMPORTANT|WARNING|CAUTION):\s*\n((?:.*\n?)*?)(?=\n\n|$)/gm, | ||
| /^(IMPORTANT|WARNING|CAUTION):\s*\n((?:[^\n]*\n?)*?)(?=\n\n|$)/gm, | ||
| "<Callout type='warn'>\n$2\n</Callout>", | ||
| ); | ||
| // Fix HTML entities globally |
| function processFile(filePath) { | ||
| try { | ||
| const content = fs.readFileSync(filePath, "utf8"); | ||
| const updatedContent = content.replace(/```rust/g, "```rust"); |
Check warning
Code scanning / CodeQL
Replacement of a substring with itself Medium documentation
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI about 9 hours ago
To fix the issue, determine the intended transformation for the string "rust". If the intention is to escape quotes, convert code fences from "rust" to another language (e.g., "```cairo"), or apply any other specific transformation, the replacement string should reflect that. Since the script is named "cairo-convert", it is very likely meant to convert Rust code fences to Cairo code fences in the docs:
- General fix: Change the replacement string from "
rust" to the intended value, such as "cairo", so that all "rust" code blocks in Markdown are converted to "cairo" blocks. - Detailed steps:
- Edit docs/scripts/cairo-convert.js at line 22.
- Change the replacement code to:
const updatedContent = content.replace(/```rust/g, "```cairo");
- No new imports or definitions are required; just the single line edit.
| @@ -19,7 +19,7 @@ | ||
| function processFile(filePath) { | ||
| try { | ||
| const content = fs.readFileSync(filePath, "utf8"); | ||
| const updatedContent = content.replace(/```rust/g, "```rust"); | ||
| const updatedContent = content.replace(/```rust/g, "```cairo"); | ||
|
|
||
| if (content !== updatedContent) { | ||
| fs.writeFileSync(filePath, updatedContent, "utf8"); |
emnul
force-pushed
the
remove-old-docs
branch
from
7805029 to
26866a7
Compare
git-subtree-dir: docs git-subtree-split: f1cf40f52fe7be77fbc603b90051262c78990556
Removes docs directory since we're now maintaining our online docs at OpenZepplin/docs. Updates GUIDELINES and CONTRIBUTING files
Closes #265
Summary by CodeRabbit
Documentation
Chores