Skip to content

Commit fa025c0

Browse files
sfc-gh-jriekejriekecursoragent
authored
Add update-docs-for-release agent skill (#1497)
* Add streamlit-release-docs agent skill Co-authored-by: Cursor <cursoragent@cursor.com> * Rename skill to update-docs-for-release, fix branch naming Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Johannes Rieke <johannes.rieke@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent a261529 commit fa025c0

1 file changed

Lines changed: 135 additions & 0 deletions

File tree

  • .cursor/skills/update-docs-for-release

‎.cursor/skills/update-docs-for-release/SKILL.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
name: update-docs-for-release
3+
description: Update the streamlit/docs repo for a new Streamlit release. Covers branch setup, release notes, API docstring generation, and API tiles/pages. Use when the user asks to update docs for a new Streamlit release, add release notes, generate docstrings, or add API tiles for new commands.
4+
disable-model-invocation: true
5+
---
6+
7+
# Streamlit release docs update
8+
9+
Follow these steps in order for each new Streamlit release (`x.y.0`).
10+
11+
## 1. Branch setup
12+
13+
Pull the latest `main` and create a release branch:
14+
15+
```bash
16+
git checkout main && git pull origin main
17+
git checkout -b docs/streamlit-x.y-release
18+
```
19+
20+
## 2. Release notes
21+
22+
You need the release notes text. If the user hasn't provided them, ask them to run the `generating-changelog` skill in the `streamlit/streamlit` repo and paste the output here.
23+
24+
**Two files to update:**
25+
26+
**`content/develop/quick-references/release-notes/_index.md`**
27+
28+
- Replace the current `## **Version x.x.0 (latest)**` section with the new release
29+
- Keep the "Older versions" links section at the bottom unchanged
30+
31+
**`content/develop/quick-references/release-notes/<year>.md`**
32+
33+
- Prepend the new version section above the previous latest release
34+
35+
Format each section as:
36+
37+
```markdown
38+
## **Version x.y.0**
39+
40+
_Release date: Month D, YYYY_
41+
42+
**Highlights**
43+
...
44+
45+
**Notable Changes**
46+
...
47+
48+
**Other Changes**
49+
...
50+
```
51+
52+
Remove any duplicate bullets from the provided notes before adding them.
53+
54+
## 3. Docstring generation
55+
56+
Run `python/generate.py` in a clean virtualenv with the correct Streamlit version.
57+
58+
```bash
59+
cd python
60+
python3 -m venv .venv-generate
61+
.venv-generate/bin/pip install -q streamlit docstring-parser docutils numpydoc
62+
.venv-generate/bin/python -c "import streamlit; print(streamlit.__version__)"
63+
.venv-generate/bin/python generate.py
64+
```
65+
66+
**Important:**
67+
68+
- Always target the `x.y.0` release key in `streamlit.json`, not patch releases (e.g. `1.59.0` not `1.59.2`). After running, rename the key if pip installed a patch release: `sed -i '' 's/"x.y.z":/"x.y.0":/' python/streamlit.json` and do the same for GitHub source URLs in the blob links.
69+
- If the script errors on a removed API (e.g. a deleted connection type), remove that entry from the `obj_key` dict in `generate.py` and re-run.
70+
- Format `streamlit.json` with Prettier after generating: `npx prettier --write python/streamlit.json`
71+
- Verify the diff: only a new `"x.y.0"` top-level key should appear — no existing version keys should be modified or removed. Check with: `git diff python/streamlit.json | grep "^@@"`— there should be exactly one hunk at the end of the file.
72+
73+
## 4. API tiles and pages
74+
75+
For each **new command** introduced in the release (not new parameters on existing commands), add a tile and detail page.
76+
77+
**Detail page** — create `content/develop/api-reference/<section>/st.<command>.md`:
78+
79+
```markdown
80+
---
81+
title: st.<command>
82+
slug: /develop/api-reference/<section>/st.<command>
83+
description: <one-line description>
84+
keywords: st.<command>, ...
85+
---
86+
87+
<Autofunction function="streamlit.<command>" />
88+
```
89+
90+
For column config types, use `content/develop/api-reference/data/column_config/<name>.md` with:
91+
92+
```markdown
93+
<Autofunction function="streamlit.column_config.<TypeName>" />
94+
```
95+
96+
**Tile** — add to both:
97+
98+
1. The section's `_index.md` (e.g. `content/develop/api-reference/status/_index.md`)
99+
2. The main `content/develop/api-reference/_index.md`
100+
101+
Tile format:
102+
103+
````markdown
104+
<RefCard href="/develop/api-reference/<section>/st.<command>">
105+
106+
<Image pure alt="screenshot" src="/images/api/<command>.jpg" />
107+
108+
<h4>Title</h4>
109+
110+
One-line description.
111+
112+
```python
113+
st.<command>(...)
114+
```
115+
````
116+
117+
</RefCard>
118+
```
119+
120+
**Menu** — add an entry in `content/menu.md` in the correct position.
121+
122+
**Images** — do not generate images. Ask the user to provide one, and point them to the Figma template file for reference:
123+
https://www.figma.com/design/MOGYWhaoD7OON4HsnbAT1z/API-illustrations?node-id=0-1&t=bs0XekxOUD8pO0to-1
124+
125+
Tell them the required format:
126+
127+
- **Format:** JPG
128+
- **Size:** 862×862px for data/widget elements, 862×816px for status/layout elements (match the dimensions of a similar existing image in `public/images/api/`)
129+
- They can also provide a PNG and you will convert it with: `sips -s format jpeg input.png --out public/images/api/<name>.jpg`
130+
131+
Place images at `public/images/api/<name>.jpg`.
132+
133+
## 5. Commit and push
134+
135+
Make focused commits per logical unit of work (release notes, docstrings, API tiles, images). Push to the branch and open a PR against `main`.

0 commit comments

Comments
 (0)