updating-docs-for-release

name	updating-docs-for-release
description	Update the streamlit/docs repo for a new Streamlit release. Covers branch setup, release notes, API docstring generation, config.toml, API tiles/pages, deprecations, and a changelog sweep of concepts, tutorials, and knowledge articles. 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.

Streamlit release docs update

Follow these steps in order for each new Streamlit release (x.y.0).

Inputs

Require the target release version in major.minor.0 format (for example, 1.63.0). If the user did not provide it, ask before starting.

Derive the previous version from python/streamlit.json as the highest semantic version below the target version. Do not calculate it by subtracting one from the minor version. If the user explicitly provides a previous version, use it as an override after confirming that its key exists in python/streamlit.json.

State the target and previous versions before making changes.

1. Branch setup

Pull the latest main and create a release branch:

git checkout main && git pull origin main
git checkout -b docs/streamlit-x.y-release

2. Release notes

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.

Two files to update:

content/develop/quick-references/release-notes/_index.md

• Replace the current ## **Version x.x.0 (latest)** section with the new release
• Keep the "Older versions" links section at the bottom unchanged

content/develop/quick-references/release-notes/<year>.md

• Prepend the new version section above the previous latest release

Format each section as:

## **Version x.y.0**

_Release date: Month D, YYYY_

**Highlights**
...

**Notable Changes**
...

**Other Changes**
...

Remove any duplicate bullets from the provided notes before adding them.

3. Docstring generation

Run python/generate.py in a clean virtualenv with the correct Streamlit version.

cd python
python3 -m venv .venv-generate
.venv-generate/bin/pip install -q streamlit docstring-parser docutils numpydoc
.venv-generate/bin/python -c "import streamlit; print(streamlit.__version__)"
.venv-generate/bin/python generate.py

Important:

• 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.
• 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.
• Format streamlit.json with Prettier after generating: npx prettier --write python/streamlit.json
• 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.

4. API tiles and pages

For each new command introduced in the release (not new parameters on existing commands), add a tile and detail page.

Detail page — create content/develop/api-reference/<section>/st.<command>.md:

---
title: st.<command>
slug: /develop/api-reference/<section>/st.<command>
description: <one-line description>
keywords: st.<command>, ...
---

<Autofunction function="streamlit.<command>" />

For column config types, use content/develop/api-reference/data/column_config/<name>.md with:

<Autofunction function="streamlit.column_config.<TypeName>" />

Tile — add to both:

1. The section's _index.md (e.g. content/develop/api-reference/status/_index.md)
2. The main content/develop/api-reference/_index.md

Tile format:

<RefCard href="/develop/api-reference/<section>/st.<command>">

<Image pure alt="screenshot" src="/images/api/<command>.jpg" />

<h4>Title</h4>

One-line description.

```python
st.<command>(...)
```

```

Menu — add an entry in content/menu.md in the correct position.

Images — do not generate images. Ask the user to provide one, and point them to the Figma template file for reference: https://www.figma.com/design/MOGYWhaoD7OON4HsnbAT1z/API-illustrations?node-id=0-1&t=bs0XekxOUD8pO0to-1

Tell them the required format:

• Format: JPG
• 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/)
• They can also provide a PNG and you will convert it with: sips -s format jpeg input.png --out public/images/api/<name>.jpg

Place images at public/images/api/<name>.jpg.

5. Example apps

New demo apps can be added both for brand-new commands and for existing commands that gained a parameter (a new example is often added to demonstrate it). So check for newly added <Cloud name="..."> embeds across all commands, not just new ones.

The reliable way to find them is to diff the embedded Cloud names between the previous and new version keys in python/streamlit.json. For example:

cd python
.venv-generate/bin/python -c "
import json, re
d = json.load(open('streamlit.json'))
def cloud_names(ver):
    out = {}
    for k, v in d[ver].items():
        for field in ('example', 'examples'):
            for m in re.findall(r'<Cloud[^>]*name=\"([^\"]+)\"', v.get(field, '') or ''):
                out.setdefault(k, set()).add(m)
    return out
prev, new = cloud_names('x.y-1.0'), cloud_names('x.y.0')
for k, names in new.items():
    added = names - prev.get(k, set())
    if added:
        print(k, sorted(added))
"

Every embed printed is a new interactive app that needs to be deployed to Community Cloud.

For each new Cloud embed found:

1. Extract the name attribute (e.g. doc-mermaid-chart) — this is the required subdomain.
2. Extract the code from the adjacent <pre> block (strip HTML tags and unescape HTML entities).
3. Save the code to python/api-examples-source/<section>.<command_or_variant>.py following the existing naming convention (e.g. charts.mermaid_chart.py, status.skeleton_standalone.py).

After adding all files, present a table to the user:

App	Deploy link	GitHub file	Subdomain
<description>	Deploy	.py	<cloud-name>

The user will handle deploying the apps to Community Cloud.

6. Configuration options

After generating docstrings, compare Streamlit's live config with the docs. The source of truth is streamlit config show from the same virtualenv used in step 3:

cd python
.venv-generate/bin/python -c "import streamlit; print(streamlit.__version__)"
.venv-generate/bin/python -m streamlit config show

Primary file: content/develop/api-reference/configuration/config-toml.md

Diff the option keys and comments from streamlit config show against that page:

• Added options — copy the CLI description into the matching [section] TOML block, using the same comment style as neighboring options.
• Changed descriptions or defaults — update the existing comments (for example allowed values, inheritance rules, or default numbers).
• Removed options — delete them from config-toml.md. If other pages still mention the option (FAQs, theming guides, tutorials), update or remove those references too.

Do not paste every theme.light.* / theme.dark.* key as its own table. Document those as inheriting from [theme] (and [theme.sidebar] where applicable), and only list exceptions that cannot be set per light/dark/sidebar.

Related pages — if theme or server options changed, check whether these still match the CLI:

• content/develop/concepts/configuration/theming.md
• content/develop/concepts/configuration/theming-fonts.md
• content/develop/concepts/configuration/theming-colors-and-borders.md

Release-note bullets about client.*, server.*, runner.*, or theme.* are a useful hint for what moved, but streamlit config show is authoritative.

7. Removed and deprecated APIs

If this version removes or deprecates commands or parameters, update the current docs to match. Start from the release notes (removal and deprecation bullets) and confirm against the new python/streamlit.json key:

cd python
.venv-generate/bin/python -c "
import json
d = json.load(open('streamlit.json'))
prev, new = d['x.y-1.0'], d['x.y.0']
print('removed commands:', sorted(set(prev) - set(new)))
for k in sorted(set(prev) & set(new)):
    old_args = {a['name'] for a in (prev[k].get('args') or [])}
    new_args = {a['name'] for a in (new[k].get('args') or [])}
    gone = sorted(old_args - new_args)
    if gone:
        print(f'removed params on {k}:', gone)
"

Do not edit historical yearly release-note pages. Search content/ (skip content/develop/quick-references/release-notes/ except the current version) plus python/api-examples-source/, python/generate.py, content/menu.md, and content/develop/quick-references/api-cheat-sheet.md.

Deprecated (still in Streamlit)

Keep the API page. Mark it so readers see the replacement:

• On the detail page Autofunction: deprecated={true} and a deprecatedText that names the version and the replacement, for example:

<Autofunction function="streamlit.<command>" deprecated={true} deprecatedText="<code>st.<command></code> was deprecated in version x.y.0 and will be removed in a later version. Use <a href='/develop/api-reference/<section>/st.<replacement>'><code>st.<replacement></code></a> instead."/>

• Add deprecated to the page keywords.
• On the section _index.md RefCard: deprecated={true}. If the section already groups deprecated APIs (for example Deprecated classes), put the tile there.
• Parameter deprecations usually flow from docstrings (.. deprecated:: is parsed into streamlit.json). Still rewrite tutorials, cheat-sheet snippets, and extra examples that recommend the old parameter as current.

Removed

Clear the command or parameter from anything that presents it as current API:

• Parameters — they drop from the new Autofunction after docstring generation. Remove them from extra examples, tutorials, concept pages, cheat-sheet snippets, and python/api-examples-source/ files. Rewrite those examples to the replacement API.
• Commands with a dedicated page — keep the slug so old links work. Strip the live Autofunction body down to a deprecation stub whose deprecatedText says the command was deprecated in version A and removed in this version, and points to the replacement (see content/develop/api-reference/charts/bokeh_chart.md). Keep the content/menu.md entry.
• Commands or methods without a dedicated page (for example a DeltaGenerator method) — delete Autofunctions, tiles, and cheat-sheet lines, and rewrite tutorials or demo apps that still call them.
• If generate.py errors because an object no longer exists, remove that entry from obj_key (or related dicts) and re-run, as in step 3.

8. Changelog sweep of existing docs

After the API, config, and deprecation steps, walk the new release notes (step 2) against the rest of the docs. New command pages, config.toml, and removal/deprecation stubs are already covered in steps 4, 6, and 7. This step is everything else that can go stale.

Treat Highlights and Notable Changes as a checklist. For Other Changes, only follow up when a bullet changes documented behavior, defaults, limitations, or recommended usage — skip routine bug fixes.

For each relevant bullet, search for the command, parameter, config key, old workaround, or limitation it touches in:

• content/develop/concepts/
• content/develop/tutorials/
• content/get-started/
• content/deploy/
• content/kb/ (knowledge base / FAQs)
• Extra prose and examples on existing API pages (anything around <Autofunction>, not the generated docstring itself)
• content/develop/quick-references/api-cheat-sheet.md
• content/develop/concepts/app-testing/cheat-sheet.md when the change affects AppTest or widget testing

Do not edit historical yearly release-note pages.

The generated Autofunction and python/streamlit.json already document new parameters. Do not add new examples, extra API-page demos, or cheat-sheet lines just to showcase a new parameter. Leave Highlights that are fully covered by the Autofunction, a new API page (step 4), or config docs (step 6) alone unless existing prose contradicts them.

It is useful to update an existing example when a new parameter is a natural fit, instead of inventing a new snippet. For example, change st.text_input("Email") to st.text_input("Email", type="email") on a form that already collects an email. Do not add a separate "email input" example only because type shipped.

Update a narrative page only when the changelog makes that page wrong or misleading, or when a highlighted capability belongs on a page that already teaches that topic:

• The page recommends a parameter, command, or workaround this version replaced or removed
• The page documents a limitation, default, or return type that no longer holds
• The page already explains the behavior that changed (for example a layouts guide that describes wrapping/stacking) and would be incomplete without the new option
• An overview page such as content/get-started/fundamentals/additional-features.md needs a short mention of a genuinely new capability (not a new kwarg on an existing command)

Rewrite in place to match current Streamlit. Do not add a new knowledge-base article unless the user asks, or an existing FAQ is now wrong and cannot be fixed with an edit.

When the sweep is done, list the pages you changed (and any changelog bullets you checked but left alone) so the user can review.

9. What's New overview

Update the homepage's What's new section in pages/index.js with one or two broadly useful, user-facing features from the new release's Highlights. Replace the same number of older feature cards so the section stays at six cards.

For each new card:

• Link directly to the feature's current concept or API page and append ?utm_source=streamlit (place any anchor after the query string).
• Use a concise title, one-sentence description, and an appropriate Material icon in the existing RefCard pattern.
• Prefer highlights with stable documentation and broad appeal. Do not feature bug fixes, deprecations, removals, or internal changes.

Keep the newest cards first and remove the oldest or least relevant cards.

10. Commit and push

Make focused commits per logical unit of work (release notes, docstrings, config, API tiles, deprecations/removals, changelog sweep, images, example apps). Push to the branch and open a PR against main.