fix(colab): Add linter for malformed lists in generated notebooks

.github/workflows/lintrunner.yml

@@ -23,6 +23,9 @@ jobs:
         with:
           python-version: '3.12'
 
+      - name: Test local linter adapters
+        run: python3 -m unittest discover -s tools/linter/tests -p 'test_*.py'
+
       - name: Install Lintrunner
         run: |
           pip install lintrunner==0.12.5

.lintrunner.toml

@@ -2,6 +2,21 @@ merge_base_with = "origin/main"
 
 # 4805a6ead6f1e7f32351056e2602be4e908f69b7 is from pytorch/pytorch main branch 2025-07-16
 
+[[linter]]
+code = 'TUTORIAL_MARKUP'
+include_patterns = [
+    'advanced_source/**/*.py',
+    'beginner_source/**/*.py',
+    'intermediate_source/**/*.py',
+    'recipes_source/**/*.py',
+    'unstable_source/**/*.py',
+]
+command = [
+    'python3',
+    'tools/linter/adapters/tutorial_markup_linter.py',
+    '@{{PATHSFILE}}',
+]
+
 [[linter]]
 code = 'SPACES'
 include_patterns = ['**']

advanced_source/usb_semisup_learn.py

@@ -71,14 +71,14 @@
 #
 # - ``get_dataset`` to load dataset, here we use CIFAR-10
 # - ``get_data_loader`` to create train (labeled and unlabeled) and test data
-# loaders, the train unlabeled loaders will provide both strong and weak
-# augmentation of unlabeled data
+#   loaders, the train unlabeled loaders will provide both strong and weak
+#   augmentation of unlabeled data
 # - ``get_net_builder`` to create a model, here we use pretrained ViT
 # - ``get_algorithm`` to create the semi-supervised learning algorithm,
-# here we use ``FreeMatch`` and ``SoftMatch``
+#   here we use ``FreeMatch`` and ``SoftMatch``
 # - ``get_config``: to get default configuration of the algorithm
 # - ``Trainer``: a Trainer class for training and evaluating the
-# algorithm on dataset
+#   algorithm on dataset
 # 
 # Note that a CUDA-enabled backend is required for training with the ``semilearn`` package.
 # See `Enabling CUDA in Google Colab <https://pytorch.org/tutorials/beginner/colab#enabling-cuda>`__ for instructions

beginner_source/basics/autogradqs_tutorial.py

@@ -87,6 +87,7 @@
 
 ######################################################################
 # .. note::
+#
 #   - We can only obtain the ``grad`` properties for the leaf
 #     nodes of the computational graph, which have ``requires_grad`` property
 #     set to ``True``. For all other nodes in our graph, gradients will not be
@@ -130,9 +131,10 @@
 
 ######################################################################
 # There are reasons you might want to disable gradient tracking:
-#   - To mark some parameters in your neural network as **frozen parameters**.
-#   - To **speed up computations** when you are only doing forward pass, because computations on tensors that do
-#     not track gradients would be more efficient.
+#
+# - To mark some parameters in your neural network as **frozen parameters**.
+# - To **speed up computations** when you are only doing forward pass, because computations on tensors that do
+#   not track gradients would be more efficient.
 
 
 ######################################################################

beginner_source/basics/data_tutorial.py

@@ -39,10 +39,11 @@
 # Each example comprises a 28×28 grayscale image and an associated label from one of 10 classes.
 #
 # We load the `FashionMNIST Dataset <https://pytorch.org/vision/stable/datasets.html#fashion-mnist>`_ with the following parameters:
-#  - ``root`` is the path where the train/test data is stored,
-#  - ``train`` specifies training or test dataset,
-#  - ``download=True`` downloads the data from the internet if it's not available at ``root``.
-#  - ``transform`` and ``target_transform`` specify the feature and label transformations
+#
+# - ``root`` is the path where the train/test data is stored,
+# - ``train`` specifies training or test dataset,
+# - ``download=True`` downloads the data from the internet if it's not available at ``root``.
+# - ``transform`` and ``target_transform`` specify the feature and label transformations
 
 
 import torch

beginner_source/blitz/neural_networks_tutorial.py

@@ -130,27 +130,30 @@ def forward(self, input):
 # Before proceeding further, let's recap all the classes you’ve seen so far.
 #
 # **Recap:**
-#   -  ``torch.Tensor`` - A *multi-dimensional array* with support for autograd
-#      operations like ``backward()``. Also *holds the gradient* w.r.t. the
-#      tensor.
-#   -  ``nn.Module`` - Neural network module. *Convenient way of
-#      encapsulating parameters*, with helpers for moving them to GPU,
-#      exporting, loading, etc.
-#   -  ``nn.Parameter`` - A kind of Tensor, that is *automatically
-#      registered as a parameter when assigned as an attribute to a*
-#      ``Module``.
-#   -  ``autograd.Function`` - Implements *forward and backward definitions
-#      of an autograd operation*. Every ``Tensor`` operation creates at
-#      least a single ``Function`` node that connects to functions that
-#      created a ``Tensor`` and *encodes its history*.
+#
+# -  ``torch.Tensor`` - A *multi-dimensional array* with support for autograd
+#    operations like ``backward()``. Also *holds the gradient* w.r.t. the
+#    tensor.
+# -  ``nn.Module`` - Neural network module. *Convenient way of
+#    encapsulating parameters*, with helpers for moving them to GPU,
+#    exporting, loading, etc.
+# -  ``nn.Parameter`` - A kind of Tensor, that is *automatically
+#    registered as a parameter when assigned as an attribute to a*
+#    ``Module``.
+# -  ``autograd.Function`` - Implements *forward and backward definitions
+#    of an autograd operation*. Every ``Tensor`` operation creates at
+#    least a single ``Function`` node that connects to functions that
+#    created a ``Tensor`` and *encodes its history*.
 #
 # **At this point, we covered:**
-#   -  Defining a neural network
-#   -  Processing inputs and calling backward
+#
+# -  Defining a neural network
+# -  Processing inputs and calling backward
 #
 # **Still Left:**
-#   -  Computing the loss
-#   -  Updating the weights of the network
+#
+# -  Computing the loss
+# -  Updating the weights of the network
 #
 # Loss Function
 # -------------

beginner_source/nn_tutorial.py

@@ -775,8 +775,9 @@ def preprocess(x):
 # -----------------------------
 #
 # Our CNN is fairly concise, but it only works with MNIST, because:
-#  - It assumes the input is a 28\*28 long vector
-#  - It assumes that the final CNN grid size is 4\*4 (since that's the average pooling kernel size we used)
+#
+# - It assumes the input is a 28\*28 long vector
+# - It assumes that the final CNN grid size is 4\*4 (since that's the average pooling kernel size we used)
 #
 # Let's get rid of these two assumptions, so our model works with any 2d
 # single channel image. First, we can remove the initial Lambda layer by
@@ -881,18 +882,19 @@ def preprocess(x, y):
 # ``torch.nn``, ``torch.optim``, ``Dataset``, and ``DataLoader``. So let's summarize
 # what we've seen:
 #
-#  - ``torch.nn``:
-#
-#    + ``Module``: creates a callable which behaves like a function, but can also
-#      contain state(such as neural net layer weights). It knows what ``Parameter`` (s) it
-#      contains and can zero all their gradients, loop through them for weight updates, etc.
-#    + ``Parameter``: a wrapper for a tensor that tells a ``Module`` that it has weights
-#      that need updating during backprop. Only tensors with the `requires_grad` attribute set are updated
-#    + ``functional``: a module(usually imported into the ``F`` namespace by convention)
-#      which contains activation functions, loss functions, etc, as well as non-stateful
-#      versions of layers such as convolutional and linear layers.
-#  - ``torch.optim``: Contains optimizers such as ``SGD``, which update the weights
-#    of ``Parameter`` during the backward step
-#  - ``Dataset``: An abstract interface of objects with a ``__len__`` and a ``__getitem__``,
-#    including classes provided with Pytorch such as ``TensorDataset``
-#  - ``DataLoader``: Takes any ``Dataset`` and creates an iterator which returns batches of data.
+# - ``torch.nn``:
+#
+#   + ``Module``: creates a callable which behaves like a function, but can also
+#     contain state(such as neural net layer weights). It knows what ``Parameter`` (s) it
+#     contains and can zero all their gradients, loop through them for weight updates, etc.
+#   + ``Parameter``: a wrapper for a tensor that tells a ``Module`` that it has weights
+#     that need updating during backprop. Only tensors with the `requires_grad` attribute set are updated
+#   + ``functional``: a module(usually imported into the ``F`` namespace by convention)
+#     which contains activation functions, loss functions, etc, as well as non-stateful
+#     versions of layers such as convolutional and linear layers.
+#
+# - ``torch.optim``: Contains optimizers such as ``SGD``, which update the weights
+#   of ``Parameter`` during the backward step
+# - ``Dataset``: An abstract interface of objects with a ``__len__`` and a ``__getitem__``,
+#   including classes provided with Pytorch such as ``TensorDataset``
+# - ``DataLoader``: Takes any ``Dataset`` and creates an iterator which returns batches of data.

intermediate_source/optimizer_step_in_backward_tutorial.py

@@ -235,12 +235,13 @@ def train(model):
 #    :alt: snapshot.png loaded into CUDA Memory Visualizer
 #
 # Several major observations:
-#  1. There is no more optimizer step! Right...we fused that into the backward.
-#  2. Likewise, the backward drags longer and there are more random allocations
-#     for intermediates. This is expected, as the optimizer step requires 
-#     intermediates.
-#  3. Most importantly! The peak memory is lower! It is now ~4GB (which I
-#     hope maps closely to your earlier expectation). 
+#
+# 1. There is no more optimizer step! Right...we fused that into the backward.
+# 2. Likewise, the backward drags longer and there are more random allocations
+#    for intermediates. This is expected, as the optimizer step requires
+#    intermediates.
+# 3. Most importantly! The peak memory is lower! It is now ~4GB (which I
+#    hope maps closely to your earlier expectation).
 # 
 # Note that there is no longer any big chunk of memory allocated for the gradients
 # compared to before, accounting for ~1.2GB of memory savings. Instead, we've freed

recipes_source/recipes/profiler_recipe.py

@@ -72,10 +72,12 @@
 # a number of parameters, some of the most useful are:
 #
 # - ``activities`` - a list of activities to profile:
-#    - ``ProfilerActivity.CPU`` - PyTorch operators, TorchScript functions and
-#      user-defined code labels (see ``record_function`` below);
-#    - ``ProfilerActivity.CUDA`` - on-device CUDA kernels;
-#    - ``ProfilerActivity.XPU`` - on-device XPU kernels;
+#
+#   - ``ProfilerActivity.CPU`` - PyTorch operators, TorchScript functions and
+#     user-defined code labels (see ``record_function`` below);
+#   - ``ProfilerActivity.CUDA`` - on-device CUDA kernels;
+#   - ``ProfilerActivity.XPU`` - on-device XPU kernels;
+#
 # - ``record_shapes`` - whether to record shapes of the operator inputs;
 # - ``profile_memory`` - whether to report amount of memory consumed by
 #   model's Tensors;

recipes_source/recipes/timer_quick_start.py

@@ -14,14 +14,15 @@
 
 
 **Contents:**
-    1. `Defining a Timer <#defining-a-timer>`__
-    2. `Wall time: Timer.blocked_autorange(...) <#wall-time-timer-blocked-autorange>`__
-    3. `C++ snippets <#c-snippets>`__
-    4. `Instruction counts: Timer.collect_callgrind(...) <#instruction-counts-timer-collect-callgrind>`__
-    5. `Instruction counts: Delving deeper <#instruction-counts-delving-deeper>`__
-    6. `A/B testing with Callgrind <#a-b-testing-with-callgrind>`__
-    7. `Wrapping up <#wrapping-up>`__
-    8. `Footnotes <#footnotes>`__
+
+1. `Defining a Timer <#defining-a-timer>`__
+2. `Wall time: Timer.blocked_autorange(...) <#wall-time-timer-blocked-autorange>`__
+3. `C++ snippets <#c-snippets>`__
+4. `Instruction counts: Timer.collect_callgrind(...) <#instruction-counts-timer-collect-callgrind>`__
+5. `Instruction counts: Delving deeper <#instruction-counts-delving-deeper>`__
+6. `A/B testing with Callgrind <#a-b-testing-with-callgrind>`__
+7. `Wrapping up <#wrapping-up>`__
+8. `Footnotes <#footnotes>`__
 """
 
 

recipes_source/torch_compiler_set_stance_tutorial.py

@@ -110,9 +110,10 @@ def outer(x):
 
 ######################################################################
 # Other stances include:
-#  - ``"default"``: The default stance, used for normal compilation.
-#  - ``"eager_on_recompile"``: Run code eagerly when a recompile is necessary. If there is cached compiled code valid for the input, it will still be used.
-#  - ``"fail_on_recompile"``: Raise an error when recompiling a function.
+#
+# - ``"default"``: The default stance, used for normal compilation.
+# - ``"eager_on_recompile"``: Run code eagerly when a recompile is necessary. If there is cached compiled code valid for the input, it will still be used.
+# - ``"fail_on_recompile"``: Raise an error when recompiling a function.
 #
 # See the ``torch.compiler.set_stance`` `doc page <https://pytorch.org/docs/main/generated/torch.compiler.set_stance.html#torch.compiler.set_stance>`__
 # for more stances and options. More stances/options may also be added in the future.