Skip to content

Commit 258a817

Browse files
fengju0213a7m-1stWendong-Fan
authored
docs: update camel doc and build cicd (#3885)
Co-authored-by: a7m-1st <[email protected]> Co-authored-by: Wendong-Fan <[email protected]>
1 parent 526578e commit 258a817

32 files changed

Lines changed: 1521 additions & 214 deletions

‎.camel/skills/docs-incremental-update/SKILL.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
name: docs-incremental-update
3+
description: >
4+
Incrementally update Mintlify documentation (.mdx) from Python source
5+
changes only. Use when: (1) Python files referenced in doc_code_map
6+
frontmatter have changed, (2) a PR touches Python modules documented in
7+
docs/mintlify/key_modules/ or docs/mintlify/mcp/, (3) the user asks to
8+
sync docs after Python code changes. Prefer minimal diffs and leave correct
9+
content untouched.
10+
---
11+
12+
# Docs Incremental Update
13+
14+
Update Mintlify .mdx documentation so it stays in sync with CAMEL source code.
15+
16+
## Scope
17+
18+
- Only use this skill when the driver is **Python source changes** referenced
19+
by a target document's `doc_code_map`.
20+
- Do **not** use it for docs-only edits, workflow/YAML changes, or broad
21+
wording cleanups without Python changes.
22+
- Prefer **no document change** when Python edits are internal and do not
23+
affect public API, behavior, configuration, examples, or reader understanding.
24+
25+
## Edit Rule
26+
27+
Use terminal tools to inspect the target doc, inspect any relevant code, and
28+
edit the target doc directly. Keep changes scoped to that doc and preserve its
29+
frontmatter.
30+
CI treats the run as successful based on the resulting target doc file state,
31+
not on any special status token in the chat response.
32+
33+
34+
## Quick Reference
35+
36+
| Item | Path |
37+
|------|------|
38+
| Doc roots | `docs/mintlify/` |
39+
| Mapping utility | `docs/mintlify/scripts/docs_sync/doc_code_map.py` |
40+
| Auto-sync script | `.camel/skills/docs-incremental-update/scripts/auto_sync_docs_with_chatagent.py` |
41+
| Workflow | `.github/workflows/docs_release_auto_sync_pr.yml` |
42+
43+
## Workflow
44+
45+
### Step 1 — Identify Impacted Docs
46+
47+
Determine which `.mdx` files are affected by the code change.
48+
49+
```bash
50+
# From repo root, pass only changed Python files
51+
python docs/mintlify/scripts/docs_sync/doc_code_map.py impacted \
52+
--changed-file <file1> --changed-file <file2>
53+
54+
# Or using git refs
55+
python docs/mintlify/scripts/docs_sync/doc_code_map.py impacted \
56+
--base-ref <base> --head-ref <head>
57+
```
58+
59+
Each `.mdx` file declares a `doc_code_map` block in its YAML frontmatter:
60+
61+
```yaml
62+
---
63+
title: MCP Toolkit
64+
doc_code_map:
65+
- "camel/toolkits/mcp_toolkit.py"
66+
- "camel/runtimes/llm_guard_runtime.py"
67+
---
68+
```
69+
70+
### Step 2 — Read Current Doc and Relevant Code
71+
72+
For each impacted doc:
73+
74+
1. Open the target `.mdx` file and inspect its `doc_code_map` frontmatter.
75+
2. Use the provided changed Python file list as initial context.
76+
3. Read any source files needed to judge whether the doc is still accurate.
77+
4. Compare the target doc against the current code and decide whether a
78+
reader-facing update is actually needed.
79+
80+
### Step 3 — Update the Document Body
81+
82+
Rewrite only the parts of the body that are outdated relative to the code.
83+
84+
Rules:
85+
- **Edit the target doc directly through terminal tools** for this run.
86+
- **Let file changes speak for themselves** — if no update is needed, leave the
87+
target doc untouched instead of relying on a sentinel reply.
88+
- **Use changed Python files as context, not a hard boundary** — inspect other
89+
relevant code when needed to make a correct documentation decision.
90+
- **Ignore non-Python changes** — docs, workflow, YAML, test-only, and release
91+
metadata changes should not trigger doc edits by themselves.
92+
- **Prefer the smallest possible diff** — keep all already-correct content.
93+
- **Preserve frontmatter** — never modify the `---` block.
94+
- **Preserve style** — keep existing section structure and tone.
95+
- **Preserve Mintlify components** — keep Card, Accordion, Tab, CodeGroup, etc.
96+
- **Update code snippets** — fix imports, class names, method signatures, parameters.
97+
- **Update prose** — fix descriptions that no longer match the code.
98+
- **Remove references** to deleted classes/methods/parameters.
99+
- **Add references** to newly introduced public API when relevant.
100+
- **Skip the document entirely** if the Python change is internal and does not
101+
require reader-facing doc updates.
102+
- After finishing, either leave the file unchanged or update it in place.
103+
- Do not return the full rewritten document body in chat; a short status note
104+
is enough.
105+
106+
### Step 4 — Verify
107+
108+
```bash
109+
# Ensure all patterns still resolve
110+
python docs/mintlify/scripts/docs_sync/doc_code_map.py verify
111+
```
112+
113+
Check that no frontmatter was accidentally removed or duplicated.
114+
115+
## Mintlify Component Cheatsheet
116+
117+
Use these components in `.mdx` files:
118+
119+
```mdx
120+
<Card title="Title" icon="icon-name" href="/path">
121+
Description text.
122+
</Card>
123+
```
124+
125+
```mdx
126+
<Accordion title="Click to expand">
127+
Hidden content revealed on click.
128+
</Accordion>
129+
```
130+
131+
```mdx
132+
<Tabs>
133+
<Tab title="Python">
134+
Python content here.
135+
</Tab>
136+
<Tab title="TypeScript">
137+
TypeScript content here.
138+
</Tab>
139+
</Tabs>
140+
```
141+
142+
~~~~mdx
143+
<CodeGroup>
144+
```python title="example.py"
145+
print("hello")
146+
```
147+
```bash title="shell"
148+
echo hello
149+
```
150+
</CodeGroup>
151+
~~~~
152+
153+
```mdx
154+
<Note>Important information the reader should know.</Note>
155+
<Warning>Critical warning about potential issues.</Warning>
156+
<Tip>Helpful suggestion or best practice.</Tip>
157+
```
158+
159+
## Automated Workflow
160+
161+
The GitHub Actions workflow `docs_release_auto_sync_pr.yml` runs
162+
automatically on each release:
163+
164+
1. Verifies `doc_code_map` patterns (`doc_code_map.py verify`).
165+
2. Writes `changed_python_files.txt` from the release diff for all changed
166+
`*.py` files that may match `doc_code_map`.
167+
3. Computes `impacted_docs.txt` from that changed Python file list.
168+
4. Runs `auto_sync_docs_with_chatagent.py` with both files so the agent knows
169+
which target doc it may inspect and update directly through terminal tools,
170+
while using `changed_python_files.txt` as context. The script accepts
171+
success based on whether the target doc actually changed and rejects edits
172+
outside the target doc.
173+
5. Opens a PR with the changes.

0 commit comments

Comments
 (0)