Removes docs directory #263

emnul · 2025-10-08T22:11:58Z

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
- Reorganized documentation structure and removed outdated API reference pages
- Updated contribution guidelines with enhanced links for new contributors
Chores
- Removed documentation build scripts and configuration files
- Updated pull request template with guidance-oriented references

andrew-fleming

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 :)

andrew-fleming · 2025-10-09T03:24:42Z

GUIDELINES.md

+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.
+


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?

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.

andrew-fleming · 2025-10-10T00:26:56Z

package.json

  "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",


We can remove --filter=!'docs' in build

coderabbitai · 2025-11-07T01:47:52Z

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.

Walkthrough

The 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

Cohort / File(s)	Summary
PR template and contributing guide updates `.github/PULL_REQUEST_TEMPLATE.md`, `CONTRIBUTING.md`, `GUIDELINES.md`	Updated PR checklist with guidance links to `CONTRIBUTING.md#your-first-code-contribution` and `GUIDELINES.md`; fixed bullet point formatting in contributing guide; added documentation guidance about external OpenZeppelin/docs repository
Documentation configuration `docs/antora.yml`	Removed Antora site configuration block (contracts-compact module, version 0.0.1, navigation, and asciidoc attributes)
Documentation navigation structure `docs/modules/ROOT/nav.adoc`	Removed all navigation entries including Overview, Learn, ZK Circuits 101, Extensibility, Modules, Tokens, and Utils sections with their xref links
API reference pages `docs/modules/ROOT/pages/api/access.adoc`, `docs/modules/ROOT/pages/api/fungibleToken.adoc`, `docs/modules/ROOT/pages/api/multitoken.adoc`, `docs/modules/ROOT/pages/api/nonFungibleToken.adoc`, `docs/modules/ROOT/pages/api/security.adoc`, `docs/modules/ROOT/pages/api/utils.adoc`	Deleted comprehensive API documentation pages for AccessControl, FungibleToken, MultiToken, NonFungibleToken, Security, and Utils modules
Module documentation pages `docs/modules/ROOT/pages/access.adoc`, `docs/modules/ROOT/pages/extensibility.adoc`, `docs/modules/ROOT/pages/fungibleToken.adoc`, `docs/modules/ROOT/pages/multitoken.adoc`, `docs/modules/ROOT/pages/nonFungibleToken.adoc`, `docs/modules/ROOT/pages/security.adoc`, `docs/modules/ROOT/pages/utils.adoc`, `docs/modules/ROOT/pages/zkCircuits101.adoc`	Removed all module documentation pages describing patterns, usage examples, constraints, and implementation guidance
Documentation index and manifest `docs/modules/ROOT/pages/index.adoc`, `docs/package.json`	Deleted main documentation landing page with setup instructions, examples, and compilation output; deleted docs package manifest
Build scripts `package.json`	Removed `docs` and `docs:watch` script entries from root package manifest

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Attention areas: Verify that all documentation files targeted for removal are included (compare against docs directory structure to ensure completeness); confirm that script removals in package.json align with the deprecation plan; validate that the updated PR template links and GUIDELINES.md additions correctly point to the new external documentation location.

Poem

🐰 The docs hop away to distant lands,
To live where OpenZeppelin stands,
Our burrows now clear, our path is bright,
Configuration scripts take graceful flight,
A new chapter starts, our branches unite! 📚✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR partially addresses the linked issue #265 requirements: removes docs tasks from package.json scripts and removes the docs directory, but does not create the docs branch or update the playbook on the old docs repo.	Complete the remaining tasks from issue #265: create a docs branch, update the playbook on OpenZeppelin/docs.openzeppelin.com to reference the new branch, and create a subtree pointing to OpenZeppelin/docs.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'Removes docs directory' directly and accurately summarizes the main change—the removal of the docs directory and related documentation files.
Out of Scope Changes check	✅ Passed	Changes to .github/PULL_REQUEST_TEMPLATE.md, CONTRIBUTING.md, and GUIDELINES.md regarding documentation links and guidance are relevant to the docs transition mentioned in PR objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

coderabbitai

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

📥 Commits

Reviewing files that changed from the base of the PR and between fb079ec and f5bc4c7.

⛔ Files ignored due to path filters (1)

yarn.lock is 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

Hey @emnul I see we have the docs branch 👍

we just need to remove the --filter=!'docs', right?

emnul · 2025-11-11T16:15:28Z

Currently blocked by OpenZeppelin/docs.openzeppelin.com#458

docs/scripts/convert-adoc.js

docs/scripts/link-validation.ts

docs/scripts/process-mdx.js

docs/scripts/cairo-convert.js

+function processFile(filePath) {
+	try {
+		const content = fs.readFileSync(filePath, "utf8");
+		const updatedContent = content.replace(/```rust/g, "```rust");


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.

git-subtree-dir: docs git-subtree-split: f1cf40f52fe7be77fbc603b90051262c78990556

andrew-fleming

Yikes, this is major major bloat with the docs repo in here. AFAICT there's no how-to in the guidelines here. The idea is to open a PR in this repo with changes to the docs and then we directly push the subtree changes (git subtree push) into the main branch of the docs? If so, I think this should be further explored and discussed outside of this PR especially with the docs team. Forgive me, I know I brought up the idea to ease friction. LMK if I'm missing something or if you disagree

emnul · 2025-11-13T16:12:11Z

Yikes, this is major major bloat with the docs repo in here. AFAICT there's no how-to in the guidelines here. The idea is to open a PR in this repo with changes to the docs and then we directly push the subtree changes (git subtree push) into the main branch of the docs? If so, I think this should be further explored and discussed outside of this PR especially with the docs team. Forgive me, I know I brought up the idea to ease friction. LMK if I'm missing something or if you disagree

Yup, the idea is essentially to colocate the docs repo in this repo so users can directly modify the external repo code without having to go back and forth between two different repos. Using subtrees also makes it easier for beginners to understand the workflow. It definitely adds bloat which is one of the major drawbacks of subtrees, alternatively we could use submodules. For our use case, we only care about updating content/compact-contracts and making sure it looks fine when the docs are built, but we would need some sort of plugin type architecture in our docs to support that rather than the monolithic structure we have now.

emnul · 2025-11-19T18:38:07Z

@andrew-fleming what do you think about the following flow as suggested by @stevedylandev

Have all *.mdx files in OpenZeppelin/docs/compact-contracts/ in OpenZeppelin/compact-contracts/docs/
Have a workflow that is triggered when changes to OpenZeppelin/compact-contracts/docs/ are made. It checks if syntax and links are valid
Have workflow in compact-contracts trigger a workflow in OpenZeppelin/docs that runs a script that clones the compact repo, copies the docs contents for a given branch, then opens a PR on the docs repo

Users can view if the build fails / everything looks right in the OpenZeppelin/docs PR, still not great DX since they can't build and test locally tho.

emnul added 5 commits October 8, 2025 17:58

Remove docs files

c783d56

fmt file

603903e

Update documentation guidelines

e1b21fa

Update pull request template

2e06257

Remove docs scripts

bbe27fc

emnul requested a review from a team as a code owner October 8, 2025 22:11

Update yarn.lock

0de7667

andrew-fleming reviewed Oct 10, 2025

View reviewed changes

Merge branch 'main' into remove-old-docs

f5bc4c7

coderabbitai bot reviewed Nov 7, 2025

View reviewed changes

andrew-fleming reviewed Nov 11, 2025

View reviewed changes

Merge branch 'main' into remove-old-docs

1c22c6f

github-advanced-security bot found potential problems Nov 11, 2025

View reviewed changes

Remove docs from workspace, turbo.json, script filters

26866a7

emnul force-pushed the remove-old-docs branch from 7805029 to 26866a7 Compare November 11, 2025 17:19

emnul added 3 commits November 11, 2025 12:21

Squashed 'docs/' content from commit f1cf40f5

e97583c

git-subtree-dir: docs git-subtree-split: f1cf40f52fe7be77fbc603b90051262c78990556

Merge commit 'e97583c7292792956e2f3d274905ddb1ce698cc2' as 'docs'

a797b37

Merge branch 'main' into remove-old-docs

8c516da

andrew-fleming reviewed Nov 13, 2025

View reviewed changes

emnul marked this pull request as draft November 13, 2025 17:04

@@ -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");

Removes docs directory #263

Are you sure you want to change the base?

Removes docs directory #263

Uh oh!

Conversation

emnul commented Oct 8, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

andrew-fleming left a comment

Choose a reason for hiding this comment

Uh oh!

andrew-fleming Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

emnul Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

andrew-fleming Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Estimated code review effort

Poem

Pre-merge checks and finishing touches

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

andrew-fleming left a comment

Choose a reason for hiding this comment

Uh oh!

emnul commented Nov 11, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Check warning

Copilot Autofix

andrew-fleming left a comment

Choose a reason for hiding this comment

Uh oh!

emnul commented Nov 13, 2025

Uh oh!

emnul commented Nov 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

emnul commented Oct 8, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Nov 7, 2025 •

edited

Loading