Contributing to Documentation

Learn how to contribute to CPython’s 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

1. Navigate to Doc directory

   cd Doc
   
2. 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
3. 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 <[e-mail]>

**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:

1. Create news entry

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

   This opens your editor to write the news entry.

2. 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.
   
3. 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

1. Create a branch

   git checkout -b doc-improve-os-module
   
2. Edit documentation

   vim Doc/library/os.rst
   
3. Build and review

   cd Doc
   make html
   make htmlview
   
4. 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:

1. Update the relevant .rst file
2. Add docstrings to the code
3. Include examples if helpful
4. 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

Next Steps

• Browse Python Documentation
• Read Documenting Python Guide
• Study Sphinx Documentation
• Review reStructuredText Primer

Additional Resources

• CPython Documentation Source
• Documenting Python
• Sphinx Documentation
• reStructuredText Guide
• Python Documentation Discourse
• Python Doc Theme