# Repository: pytorch/tutorials # Stars: 9115 ## CLAUDE.md # 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. ## README.md # PyTorch Tutorials All the tutorials are now presented as sphinx style documentation at: ## [https://pytorch.org/tutorials](https://pytorch.org/tutorials) # Asking a question If you have a question about a tutorial, post in https://dev-discuss.pytorch.org/ rather than creating an issue in this repo. Your question will be answered much faster on the dev-discuss forum. # Submitting an issue You can submit the following types of issues: * Feature request - request a new tutorial to be added. Please explain why this tutorial is needed and how it demonstrates PyTorch value. * Bug report - report a failure or outdated information in an existing tutorial. When submitting a bug report, please run: `python3 -m torch.utils.collect_env` to get information about your environment and add the output to the bug report. # Contributing We use sphinx-gallery's [notebook styled examples](https://sphinx-gallery.github.io/stable/tutorials/index.html) to create the tutorials. Syntax is very simple. In essence, you write a slightly well formatted Python file and it shows up as an HTML page. In addition, a Jupyter notebook is autogenerated and available to run in Google Colab. Here is how you can create a new tutorial (for a detailed description, see [CONTRIBUTING.md](./CONTRIBUTING.md)): NOTE: Before submitting a new tutorial, read [PyTorch Tutorial Submission Policy](./tutorial_submission_policy.md). 1. Create a Python file. If you want it executed while inserted into documentation, save the file with the suffix `tutorial` so that the file name is `your_tutorial.py`. 2. Put it in one of the `beginner_source`, `intermediate_source`, `advanced_source` directory based on the level of difficulty. If it is a recipe, add it to `recipes_source`. For tutorials demonstrating unstable prototype features, add to the `prototype_source`. 3. For Tutorials (except if it is a prototype feature), include it in the `toctree` directive and create a `customcarditem` in [index.rst](./index.rst). 4. For Tutorials (except if it is a prototype feature), create a thumbnail in the [index.rst file](https://github.com/pytorch/tutorials/blob/main/index.rst) using a command like `.. customcarditem:: beginner/your_tutorial.html`. For Recipes, create a thumbnail in the [recipes_index.rst](https://github.com/pytorch/tutorials/blob/main/recipes_index.rst) If you are starting off with a Jupyter notebook, you can use [this script](https://gist.github.com/chsasank/7218ca16f8d022e02a9c0deb94a310fe) to convert the notebook to Python file. After conversion and addition to the project, please make sure that section headings and other things are in logical order. ## Building locally The tutorial build is very large and requires a GPU. If your machine does not have a GPU device, you can preview your HTML build without actually downloading the data and running the tutorial code: 1. Install required dependencies by running: `pip install -r requirements.txt`. > Typically, you would run either in `conda` or `virtualenv`. If you want to use `virtualenv`, in the root of the repo, run: `virtualenv venv`, then `source venv/bin/activate`. - If you have a GPU-powered laptop, you can build using `make docs`. This will download the data, execute the tutorials and build the documentation to `docs/` directory. This might take about 60-120 min for systems with GPUs. If you do not have a GPU installed on your system, then see next step. - You can skip the computationally intensive graph generation by running `make html-noplot` to build basic html documentation to `_build/html`. This way, you can quickly preview your tutorial. ## Building a single tutorial You can build a single tutorial by using the `GALLERY_PATTERN` environment variable. For example to run only `neural_style_transfer_tutorial.py`, run: ``` GALLERY_PATTERN="neural_style_transfer_tutorial.py" make html ``` or ``` GALLERY_PATTERN="neural_style_transfer_tutorial.py" sphinx-build . _build ``` The `GALLERY_PATTERN` variable respects regular expressions. ## Spell Check You can run pyspelling to check for spelling errors in the tutorials. To check only Python files, run pyspelling -n python. To check only .rst files, use pyspelling -n reST. Currently, .rst spell checking is limited to the beginner/ directory. Contributions to enable spell checking in other directories are welcome! ``` pyspelling # full check (~3 mins) pyspelling -n python # Python files only pyspelling -n reST # reST files (only beginner/ dir currently included) ``` ## About contributing to PyTorch Documentation and Tutorials * You can find information about contributing to PyTorch documentation in the PyTorch Repo [README.md](https://github.com/pytorch/pytorch/blob/master/README.md) file. * Additional information can be found in [PyTorch CONTRIBUTING.md](https://github.com/pytorch/pytorch/blob/master/CONTRIBUTING.md). ## License PyTorch Tutorials is BSD licensed, as found in the LICENSE file.