Skip to content

ci: add docs-sync workflow to open PRs against dojoengine/book #3405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
kronosapiens wants to merge 1 commit into from
+20 −183
Closed

ci: add docs-sync workflow to open PRs against dojoengine/book #3405

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 20 additions & 183 deletions .github/workflows/docs-sync.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: doc-sync
name: docs-sync

on:
pull_request:
Expand All @@ -14,185 +14,22 @@ on:
jobs:
docs-sync:
if: github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch'
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
id-token: write

steps:
- name: Checkout dojo repository
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Get changed files
id: changed-files
run: |
set -e
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
git fetch origin
DIFF_BASE="${{ github.event.inputs.commit_sha }}~1"
DIFF_HEAD="${{ github.event.inputs.commit_sha }}"
else
git fetch origin main
DIFF_BASE="${{ github.event.pull_request.base.sha }}"
DIFF_HEAD="${{ github.event.pull_request.merge_commit_sha }}"
fi
CHANGED_FILES=$(git diff --name-only "$DIFF_BASE" "$DIFF_HEAD")
DIFF_CONTENT=$(git diff "$DIFF_BASE" "$DIFF_HEAD" -- '*.rs' '*.cairo' '*.toml' '*.md' | head -c 60000)
echo "changed_files<<EOF" >> $GITHUB_OUTPUT
echo "$CHANGED_FILES" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
echo "diff_content<<EOF" >> $GITHUB_OUTPUT
echo "$DIFF_CONTENT" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT

- name: Check if docs update needed
id: check-docs
run: |
# Check if changes require documentation updates
NEEDS_DOCS_UPDATE=false

# Define patterns that typically require docs updates
DOCS_PATTERNS=(
"^crates/.*\.rs$"
"^crates/.*\.cairo$"
"^crates/.*\.toml$"
"^bin/.*\.rs$"
"^bin/.*\.toml$"
"^README\.md$"
"^CHANGELOG\.md$"
)

while IFS= read -r file; do
for pattern in "${DOCS_PATTERNS[@]}"; do
if [[ $file =~ $pattern ]]; then
NEEDS_DOCS_UPDATE=true
break 2
fi
done
done <<< "${{ steps.changed-files.outputs.changed_files }}"

echo "needs_update=$NEEDS_DOCS_UPDATE" >> $GITHUB_OUTPUT
echo "Files that may need docs updates: $(echo '${{ steps.changed-files.outputs.changed_files }}' | tr '\n' ' ')"

- name: Checkout docs repository
if: steps.check-docs.outputs.needs_update == 'true'
uses: actions/checkout@v4
with:
repository: dojoengine/book
token: ${{ secrets.CREATE_PR_TOKEN }}
path: docs-repo

- name: Analyze changes and update docs
if: steps.check-docs.outputs.needs_update == 'true'
uses: anthropics/claude-code-action@beta
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
model: "claude-sonnet-4-5-20250929"
direct_prompt: |
Analyze changes in this dojo repository and update documentation
in the dojoengine/book repository ONLY if user-facing behavior changed.

**Change Information:**
- Title: ${{ github.event.pull_request.title || format('Manual trigger for commit {0}', github.event.inputs.commit_sha) }}
- Description: ${{ github.event.pull_request.body || 'Manually triggered documentation sync' }}
- Files changed: ${{ steps.changed-files.outputs.changed_files }}
- Commit SHA: ${{ github.event.pull_request.merge_commit_sha || github.event.inputs.commit_sha }}

**Diff of changed files:**
${{ steps.changed-files.outputs.diff_content }}

**Docs repo structure** (checked out in `docs-repo/`):
The site uses Vocs. Content lives in `docs-repo/docs/pages/` with these sections:
- `getting-started/` — Your First Dojo App, Understanding the Toolchain, Development Workflow
- `framework/` — world/, models/, systems/, testing/, upgrading/, configuration/
- `toolchain/` — sozo/, katana/, torii/, saya/, cainome
- `client/sdk/` — dojo.js, dojo.c, dojo.unity, dojo.unreal, dojo.godot, dojo.bevy, dojo.rust, dojo.telegram
- `tutorials/` — Dojo 101, Deploy to Mainnet, Deploy using Slot
- `libraries/` — Origami, Alexandria
- `scaling/` — Execution Sharding, Sovereign Rollups
Sidebar config is in `docs-repo/routes.ts`, imported by `docs-repo/vocs.config.ts`.

**Rules — read these carefully:**
1. DEFAULT TO NO CHANGES. Most code PRs do not need docs updates. Internal refactors, test changes, CI changes, and dependency bumps need nothing. Only proceed if there is a concrete user-facing change (new API, changed behavior, new feature, removed feature, changed configuration).
2. SINGLE CANONICAL LOCATION. Each piece of information belongs on exactly one page. Find the one page that owns the topic and make your substantive edits there. Other pages MAY add a brief cross-reference linking to the canonical page, but do NOT duplicate explanations, code samples, or configuration details across multiple pages.
3. MINIMAL EDITS. Update only the specific section affected. Do not rewrite surrounding paragraphs, add new sections for context, or reorganize existing content.
4. ONE CODE EXAMPLE per concept. If a code sample is needed, add it once in the canonical location. Do not add the same or similar examples to multiple pages.
5. Do NOT create git branches, commits, or PRs — just update files.
6. If no documentation updates are needed, state that clearly and exit.

allowed_tools: "Read,Write,Edit,MultiEdit,Glob,Grep"

- name: Create branch and commit changes
if: steps.check-docs.outputs.needs_update == 'true'
working-directory: docs-repo
run: |
# Configure git
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"

# Check if there are any changes
if [ -n "$(git status --porcelain)" ]; then
# Create new branch
BRANCH_NAME="docs-update-$(date +%s)"
git checkout -b "$BRANCH_NAME"

# Add and commit changes
git add .
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
git commit -m "docs: Update documentation for dojo commit ${{ github.event.inputs.commit_sha }}

Updates documentation to reflect changes made in commit:
${{ github.event.inputs.commit_sha }}

Manually triggered documentation sync"
else
git commit -m "docs: Update documentation for dojo PR #${{ github.event.pull_request.number }}

Updates documentation to reflect changes made in:
${{ github.event.pull_request.title }}

Related dojo PR: dojoengine/dojo#${{ github.event.pull_request.number }}"
fi

# Push branch
git push origin "$BRANCH_NAME"

# Create PR
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
PR_URL=$(gh pr create \
--title "docs: Update documentation for dojo commit ${{ github.event.inputs.commit_sha }}" \
--body "This PR updates the documentation to reflect changes made in dojoengine/dojo commit ${{ github.event.inputs.commit_sha }}

**Commit Details:**
- Commit SHA: ${{ github.event.inputs.commit_sha }}
- Files changed: ${{ steps.changed-files.outputs.changed_files }}
- Trigger: Manual documentation sync

Please review the documentation changes to ensure they accurately reflect the dojo updates.")
gh pr merge "$PR_URL" --auto --squash
else
PR_URL=$(gh pr create \
--title "docs: Update documentation for dojo PR #${{ github.event.pull_request.number }}" \
--body "This PR updates the documentation to reflect changes made in dojoengine/dojo#${{ github.event.pull_request.number }}

**Original PR Details:**
- Title: ${{ github.event.pull_request.title }}
- Files changed: ${{ steps.changed-files.outputs.changed_files }}

Please review the documentation changes to ensure they accurately reflect the dojo updates.")
gh pr merge "$PR_URL" --auto --squash
fi
else
echo "No documentation changes were made by Claude"
fi
env:
GITHUB_TOKEN: ${{ secrets.CREATE_PR_TOKEN }}

- name: Cleanup
if: always()
run: |
# Clean up any temporary files or directories
rm -rf docs-repo || true
uses: dojoengine/book/.github/workflows/docs-sync.yml@main
Comment thread
kronosapiens marked this conversation as resolved.
with:
target-docs-repo: dojoengine/book
source-repo-slug: dojoengine/dojo
diff-globs: |
*.rs
*.cairo
*.toml
*.md
docs-patterns: |
^crates/.*\.(rs|cairo)$
^bin/.*\.(rs|cairo)$
canonical-desc: |
The Dojo framework and sozo CLI are documented in two sections of dojoengine/book:
- docs-repo/docs/pages/framework/ — World, models, systems, events, testing, authorization, config
- docs-repo/docs/pages/toolchain/sozo/ — sozo CLI commands and workflows
Comment on lines +29 to +32
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Ohayo sensei — stray indentation inside canonical-desc.

Lines 31–32 carry ~20 extra leading spaces before the - bullets, which the YAML block scalar preserves verbatim when forwarded to Claude. Not a bug, but the prompt string will render with a weird hanging indent compared to the other *-desc inputs. Trim to match the indent of line 30.

✂️ Proposed tidy-up 
       canonical-desc: |
         The Dojo framework and sozo CLI are documented in two sections of dojoengine/book:
-                    - docs-repo/docs/pages/framework/ — World, models, systems, events, testing, authorization, config
-                    - docs-repo/docs/pages/toolchain/sozo/ — sozo CLI commands and workflows
+        - docs-repo/docs/pages/framework/ — World, models, systems, events, testing, authorization, config
+        - docs-repo/docs/pages/toolchain/sozo/ — sozo CLI commands and workflows
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
canonical-desc: |
The Dojo framework and sozo CLI are documented in two sections of dojoengine/book:
- docs-repo/docs/pages/framework/ — World, models, systems, events, testing, authorization, config
- docs-repo/docs/pages/toolchain/sozo/ — sozo CLI commands and workflows
canonical-desc: |
The Dojo framework and sozo CLI are documented in two sections of dojoengine/book:
- docs-repo/docs/pages/framework/ — World, models, systems, events, testing, authorization, config
- docs-repo/docs/pages/toolchain/sozo/ — sozo CLI commands and workflows
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/docs-sync.yml around lines 29 - 32, The YAML block under
canonical-desc contains extra leading spaces on the two bullet lines causing a
preserved hanging indent; edit the canonical-desc block so the two list lines
start at the same column as the first description line (remove the ~20 extra
spaces before "- docs-repo/docs/pages/framework/..." and "-
docs-repo/docs/pages/toolchain/sozo/..."), ensuring the block scalar preserves
the intended alignment when consumed by the downstream prompt processor; verify
the resulting indentation matches the line with "The Dojo framework..." so
rendering is consistent.

docs-structure-desc: |
The site uses Vocs. Content lives in `docs-repo/docs/pages/`. Navigation is in `docs-repo/routes.ts`. SDK docs at `docs-repo/docs/pages/client/sdk/` are single `.md` files (bevy.md, javascript.md, unity.md, unrealengine.md, godot.md, rust.md, telegram.md), not subdirectories — the sole exception is `c/` which is a subdir.
secrets: inherit
Comment thread
kronosapiens marked this conversation as resolved.
Loading