Project Structure

This is the PyTorch Tutorials website (pytorch.org/tutorials), built with Sphinx and Sphinx Gallery.

• beginner_source/, intermediate_source/, advanced_source/, recipes_source/, unstable_source/ — tutorial source files (.py and .rst)

• index.rst, recipes_index.rst — card listings and toctrees for the website

• conf.py — Sphinx configuration (gallery dirs, extensions, theme)

• _static/ — images, CSS, and thumbnails

• requirements.txt — all Python dependencies (Sphinx, tutorial packages)

• .jenkins/ — CI build scripts, data download logic, post-processing

• Makefile — build entry points

Tutorials authored as .py files use Sphinx Gallery format: top-level docstrings become RST prose, code blocks become executable cells. These are executed during builds and converted to Jupyter notebooks and HTML. Tutorials authored as .rst are static and their code is not executed.

Build

• make html-noplot — builds HTML without executing tutorial code. Fast, no GPU needed. Use this for quick validation of RST/Sphinx structure.

• make docs — full build that downloads data, executes all .py tutorials, and produces the final site. Requires a GPU-powered machine with CUDA.

• GALLERY_PATTERN="my_tutorial.py" make html — build only a single tutorial by name (regex supported).

The CI build runs inside Docker across 15 GPU-powered shards via .jenkins/build.sh.

Linting

This repo uses lintrunner. Do not use spin, flake8, or other linters directly.

• lintrunner -m main — lint changes relative to the main branch

• lintrunner --all-files — lint all files in the repo

Lintrunner checks trailing whitespace, tabs, and newline issues only. It does not check Python formatting, RST syntax, or Sphinx directives.

Testing

There is no unit test suite. Validation is done by building tutorials:

• make html-noplot is the quick sanity check for RST and Sphinx errors.

• Full execution of .py tutorials runs in CI on GPU shards.

• To test a single tutorial: GALLERY_PATTERN="my_tutorial.py" make html

Tutorial File Format

• Interactive tutorials are .py files using Sphinx Gallery conventions. Filenames should end in _tutorial.py.

• Non-interactive tutorials are .rst files.

• Data dependencies must be added via .jenkins/download_data.py, not the Makefile. Follow the existing patterns in that file.

• New Python package dependencies go in requirements.txt.

Adding a New Tutorial

1. Place the file in the appropriate *_source/ directory based on difficulty level.

2. Add a customcarditem entry in index.rst (or recipes_index.rst for recipes).

3. Add the tutorial to the corresponding toctree in index.rst.

4. Add a square, high-resolution thumbnail image to _static/img/thumbnails/cropped/.

Coding Style Guidelines

Follow these rules for all code changes in this repository:

• Minimize comments; be concise; code should be self-explanatory.

• Match existing code style and architectural patterns.

• Tutorial prose should be written for a global audience with clear, easy to understand language. Avoid idioms.

• Use active voice in tutorial instructions.

• If uncertain, choose the simpler, more concise implementation.