docs

name	docs
description	Use this skill when editing documentation, working with files in Doc/, adding versionadded or versionchanged markers, creating NEWS entries for bug fixes or features, updating What's New (Doc/whatsnew/), or building the HTML docs. Covers reStructuredText (.rst) format, documentation validation, and NEWS file requirements.

CPython Documentation

CPython documentation is in reStructuredText (ReST) format in the Doc/ tree.

Documentation Tooling

# Set up documentation build environment
make -C Doc venv

# Validate documentation (run this to check your changes)
make -C Doc check

# Build HTML documentation (if full build is needed)
make -C Doc html

Version Markers

IMPORTANT: When adding versionadded::, versionchanged::, or similar markers in documentation, always use next as the version "number". The doc build and release process fills this in appropriately.

.. versionadded:: next

.. versionchanged:: next
   Description of what changed.

NEWS Entries

Bug fixes and new features require a Misc/NEWS.d/next/ file entry.

IMPORTANT: The filename MUST refer to the correct GitHub Issue number in the upstream python/cpython repository. Do not pick a number on your own! Ask the user what issue number to use.

Filename format: Misc/NEWS.d/next/<CATEGORY>/<YYYY-MM-DD-HH-MM-SS>.gh-issue-<NUMBER>.<NONCE>.rst

• <CATEGORY>: must be one of the existing directory names under Misc/NEWS.d/next/ on the current branch — list that directory to see the valid set (e.g. Library, Core_and_Builtins, C_API); don't invent a category.
• <YYYY-MM-DD-HH-MM-SS>: the current UTC time.
• <NONCE>: 6 characters from the urlsafe-base64 alphabet (A-Z a-z 0-9 _ -), e.g. _f-cFH. Any unique value works; it only prevents filename collisions.

Entry body: one or a few complete sentences describing the user-visible change, using Sphinx roles (:func:, :class:, :meth:, :exc:, :mod:) to link the affected APIs. Don't write "Fixes gh-NNNN" in the body — the filename already carries the issue link. Example:

When a worker process terminates unexpectedly,
:class:`concurrent.futures.ProcessPoolExecutor` now sets a separate
:exc:`~concurrent.futures.process.BrokenProcessPool` exception on each
pending future instead of sharing a single instance among them all.

What's New

User-visible changes worth highlighting to people upgrading also get an entry in the in-development release's Doc/whatsnew/<version>.rst (the highest-numbered file in Doc/whatsnew/), in the section for the affected module. Follow the style of neighboring entries. Not every NEWS entry needs one — reserve it for changes a typical upgrader would care about. (The backport skill covers what happens to whatsnew entries when a change is backported.)