Contributing to Documentation

CPython’s documentation is written in reStructuredText and built with Sphinx. This guide covers how to build, edit, and contribute to the documentation.

Documentation Overview

CPython documentation is located in the Doc/ directory and includes:

Library reference: Standard library documentation
Language reference: Python language specification
C API reference: CPython C API documentation
Tutorials: Getting started guides
How-tos: Task-focused guides
FAQs: Frequently asked questions

You don’t need to build documentation yourself - prebuilt versions are available.

Setting Up Documentation Build

Install Dependencies

Navigate to Doc directory

cd Doc

Create virtual environment

make venv

This creates a virtual environment in Doc/venv with all necessary tools:

Sphinx: Documentation builder
blurb: News entry tool
python-docs-theme: Python documentation theme

Build HTML documentation

make html

The built documentation will be in Doc/build/html/.

You can specify a custom virtual environment location with VENVDIR:

make venv VENVDIR=~/my-doc-env

Alternative: Without make

If you can’t use make:

# Install dependencies manually
pip install sphinx blurb python-docs-theme

# Build from Doc directory
sphinx-build -b html . build/html

Building Documentation

Available Build Targets

# HTML for offline viewing
make html

# Open in browser after building
make htmlview

# HTML with live reload (Unix only)
make htmllive

# Plain text output
make text

# EPUB for e-readers
make epub

# LaTeX for PDF generation
make latex

# Check for broken links
make linkcheck

# Check for markup errors
make check

# Clean build files
make clean

Windows Build

On Windows, use make.bat:

cd Doc
make.bat html
make.bat htmlview

Set the PYTHON environment variable if needed:

set PYTHON=C:\Path\To\python.exe
make.bat html

reStructuredText Basics

CPython documentation uses reStructuredText (reST) markup.

Headings

Main Title
==========

Section
-------

Subsection
^^^^^^^^^^

Subsubsection
~~~~~~~~~~~~~

Paragraphs and Text Formatting

This is a paragraph. Paragraphs are separated by blank lines.

*Italic text* and **bold text**.

``Inline code`` uses double backticks.

A literal block::

    def example():
        return "indented code block"

Code Blocks

Python code:

.. code-block:: python

    def greet(name):
        """Greet someone."""
        print(f"Hello, {name}!")

C code:

.. code-block:: c

    static PyObject *
    greet(PyObject *self, PyObject *args)
    {
        /* C implementation */
    }

Links

`External link <https://www.python.org/>`_

:ref:`Internal cross-reference <label-name>`

:func:`os.path.join` - Link to function
:class:`dict` - Link to class
:mod:`os` - Link to module
:pep:`8` - Link to PEP

Lists

Bulleted list:

* Item one
* Item two

  * Nested item
  * Another nested

* Item three

Numbered list:

#. First
#. Second
#. Third

Definition list:

Term
    Definition of the term

Another term
    Its definition

Admonitions

.. note::

    This is a note.

.. warning::

    This is a warning.

.. versionadded:: 3.15

.. versionchanged:: 3.15
    Description of the change.

.. deprecated:: 3.15
    Use :func:`new_function` instead.

Documenting Python Code

Module Documentation

Create or edit files in Doc/library/:

:mod:`mymodule` --- Brief description
======================================

.. module:: mymodule
   :synopsis: Brief description.

.. moduleauthor:: Your Name <your.email@example.com>

**Source code:** :source:`Lib/mymodule.py`

--------------

Detailed description of the module.

.. function:: my_function(arg1, arg2)

   Description of the function.

   :param arg1: Description of arg1.
   :type arg1: str
   :param arg2: Description of arg2.
   :type arg2: int
   :return: Description of return value.
   :rtype: bool
   :raises ValueError: When arg1 is invalid.

.. class:: MyClass

   Description of the class.

   .. method:: method_name(param)

      Description of the method.

Function Documentation

.. function:: open(file, mode='r', buffering=-1)

   Open file and return a corresponding file object.

   *file* is either a string or bytes object giving the pathname.

   *mode* is an optional string that specifies the mode in which
   the file is opened. It defaults to ``'r'``.

   :param file: Path to the file
   :type file: str or bytes
   :param mode: File opening mode
   :type mode: str
   :return: File object
   :rtype: file object
   :raises FileNotFoundError: If file doesn't exist

Class Documentation

.. class:: MyClass(arg1, arg2=None)

   A class that does something.

   :param arg1: First argument
   :param arg2: Optional second argument

   .. attribute:: value

      The value attribute.

   .. method:: process(data)

      Process the data.

      :param data: Data to process
      :returns: Processed result

Documenting C API

C Function Documentation

In Doc/c-api/*.rst:

.. c:function:: PyObject* PyDict_New()

   Return a new empty dictionary, or *NULL* on failure.

   .. note::

      This function always succeeds in practice, but returns
      *NULL* for consistency with other APIs.

.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

   Insert *value* into the dictionary with the given *key*.

   :param p: Dictionary object
   :param key: Key object
   :param val: Value object
   :return: ``0`` on success, ``-1`` on failure

C Type Documentation

.. c:type:: PyDictObject

   This subtype of :c:type:`PyObject` represents a Python
   dictionary object.

.. c:member:: Py_ssize_t PyDictObject.ma_used

   Number of items in the dictionary.

Adding News Entries

For significant changes, add a news entry using blurb:

Create news entry

# In the CPython root directory
./python -m blurb add

This opens your editor to write the news entry.

Write the entry

Describe the change clearly and concisely:

Fixed memory leak in :func:`os.fspath` when handling
path-like objects with custom __fspath__ methods.

Save and commit

The entry is saved to Misc/NEWS.d/next/. Commit it with your changes:

git add Misc/NEWS.d/next/
git commit

News entries are categorized by type:

Core and Builtins: Interpreter core
Library: Standard library
Documentation: Documentation changes
Tests: Test suite changes
Build: Build system changes
Windows: Windows-specific changes
macOS: macOS-specific changes
IDLE: IDLE changes
Tools-Demos: Tools and demos
C API: C API changes

Documentation Style Guide

Voice and Tone

Use active voice: “Returns a list” not “A list is returned”
Be concise but complete
Use present tense: “Creates” not “Will create”
Address the reader as “you” when appropriate

Technical Style

Good:
    The :func:`open` function returns a file object.
    
Bad:
    open() returns a file object.

Parameter Documentation

Good:
    :param str name: The name of the file
    :param int mode: File permissions (default: 0o644)
    
Bad:
    :param name: name

Examples

Include examples when helpful:

.. function:: greet(name)

   Print a greeting.

   Example::

       >>> greet("World")
       Hello, World!

Checking Your Documentation

Syntax Check

cd Doc
make check

This checks for:

Syntax errors
Broken references
Formatting issues

Link Check

make linkcheck

This verifies all external links are valid.

Build and Review

# Build and open in browser
make htmlview

# Or manually
make html
open build/html/index.html  # macOS
xdg-open build/html/index.html  # Linux

Contributing Documentation

Documentation-Only Changes

Create a branch

git checkout -b doc-improve-os-module

Edit documentation

vim Doc/library/os.rst

Build and review

cd Doc
make html
make htmlview

Commit and push

git add Doc/library/os.rst
git commit -m "gh-12345: Improve os module documentation"
git push origin doc-improve-os-module

Documentation with Code Changes

When adding features:

Update the relevant .rst file
Add docstrings to the code
Include examples if helpful
Add a news entry with blurb

Troubleshooting

Sphinx build errors

Common issues:

# Rebuild from scratch
make clean
make html

# Check for syntax errors
make check

Missing dependencies

Reinstall documentation tools:

cd Doc
make clean-venv
make venv
make html

Broken cross-references

Use the correct role:

:func:`function_name`  # For functions
:class:`ClassName`     # For classes
:mod:`module`          # For modules
:meth:`obj.method`     # For methods

blurb not found

Install blurb:

pip install blurb
# Or use the venv
cd Doc
make venv
source venv/bin/activate

Best Practices

Keep it simple: Use clear, straightforward language
Show examples: Include code examples when helpful
Link generously: Cross-reference related functions
Update thoroughly: Update all affected docs
Test the docs: Build and review HTML output
Follow style: Match existing documentation style
Spell check: Use a spell checker

Getting Started

Development

Documentation Index

​Documentation Overview

​Setting Up Documentation Build

​Install Dependencies

​Alternative: Without make

​Building Documentation

​Available Build Targets

​Windows Build

​reStructuredText Basics

​Headings

​Paragraphs and Text Formatting

​Code Blocks

​Links

​Lists

​Admonitions

​Documenting Python Code

​Module Documentation

​Function Documentation

​Class Documentation

​Documenting C API

​C Function Documentation

​C Type Documentation

​Adding News Entries

​Documentation Style Guide

​Voice and Tone

​Technical Style

​Parameter Documentation

​Examples

​Checking Your Documentation

​Syntax Check

​Link Check

​Build and Review

​Contributing Documentation

​Documentation-Only Changes

​Documentation with Code Changes

​Troubleshooting

​Best Practices

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

Documentation Overview

Setting Up Documentation Build

Install Dependencies

Alternative: Without make

Building Documentation

Available Build Targets

Windows Build

reStructuredText Basics

Headings

Paragraphs and Text Formatting

Code Blocks

Links

Lists

Admonitions

Documenting Python Code

Module Documentation

Function Documentation

Class Documentation

Documenting C API

C Function Documentation

C Type Documentation

Adding News Entries

Documentation Style Guide

Voice and Tone

Technical Style

Parameter Documentation

Examples

Checking Your Documentation

Syntax Check

Link Check

Build and Review

Contributing Documentation

Documentation-Only Changes

Documentation with Code Changes

Troubleshooting

Best Practices

Next Steps

Additional Resources