Split example gallery into subsections

docs/source/conf.py

@@ -30,6 +30,7 @@
 import torchvision
 import torchvision.models as M
 from tabulate import tabulate
+from sphinx_gallery.sorting import ExplicitOrder
 
 sys.path.append(os.path.abspath("."))
 
@@ -61,6 +62,7 @@
 sphinx_gallery_conf = {
     "examples_dirs": "../../gallery/",  # path to your example scripts
     "gallery_dirs": "auto_examples",  # path to where to save gallery generated output
+    'subsection_order': ExplicitOrder(["../../gallery/v2_transforms", "../../gallery/others"]),
     "backreferences_dir": "gen_modules/backreferences",
     "doc_module": ("torchvision",),
     "remove_config_comments": True,

docs/source/datapoints.rst

@@ -6,7 +6,7 @@ Datapoints
 Datapoints are tensor subclasses which the :mod:`~torchvision.transforms.v2` v2 transforms use under the hood to
 dispatch their inputs to the appropriate lower-level kernels. Most users do not
 need to manipulate datapoints directly and can simply rely on dataset wrapping -
-see e.g. :ref:`sphx_glr_auto_examples_plot_transforms_v2_e2e.py`.
+see e.g. :ref:`sphx_glr_auto_examples_v2_transforms_plot_transforms_v2_e2e.py`.
 
 .. autosummary::
     :toctree: generated/

docs/source/transforms.rst

@@ -13,7 +13,7 @@ Transforming and augmenting images
     are fully backward compatible with the current ones, and you'll see them
     documented below with a `v2.` prefix. To get started with those new
     transforms, you can check out
-    :ref:`sphx_glr_auto_examples_plot_transforms_v2_e2e.py`.
+    :ref:`sphx_glr_auto_examples_v2_transforms_plot_transforms_v2_e2e.py`.
     Note that these transforms are still BETA, and while we don't expect major
     breaking changes in the future, some APIs may still change according to user
     feedback. Please submit any feedback you may have `here
@@ -54,15 +54,15 @@ across calls. For reproducible transformations across calls, you may use
 
 The following examples illustrate the use of the available transforms:
 
-    * :ref:`sphx_glr_auto_examples_plot_transforms.py`
+    * :ref:`sphx_glr_auto_examples_others_plot_transforms.py`
 
-        .. figure:: ../source/auto_examples/images/sphx_glr_plot_transforms_001.png
+        .. figure:: ../source/auto_examples/others/images/sphx_glr_plot_transforms_001.png
             :align: center
             :scale: 65%
 
-    * :ref:`sphx_glr_auto_examples_plot_scripted_tensor_transforms.py`
+    * :ref:`sphx_glr_auto_examples_others_plot_scripted_tensor_transforms.py`
 
-        .. figure:: ../source/auto_examples/images/sphx_glr_plot_scripted_tensor_transforms_001.png
+        .. figure:: ../source/auto_examples/others/images/sphx_glr_plot_scripted_tensor_transforms_001.png
             :align: center
             :scale: 30%
 
@@ -269,7 +269,7 @@ CutMix and MixUp are special transforms that
 are meant to be used on batches rather than on individual images, because they
 are combining pairs of images together. These can be used after the dataloader
 (once the samples are batched), or part of a collation function. See
-:ref:`sphx_glr_auto_examples_plot_cutmix_mixup.py` for detailed usage examples.
+:ref:`sphx_glr_auto_examples_v2_transforms_plot_cutmix_mixup.py` for detailed usage examples.
 
 .. autosummary::
     :toctree: generated/

docs/source/utils.rst

@@ -4,7 +4,7 @@ Utils
 =====
 
 The ``torchvision.utils`` module contains various utilities, mostly :ref:`for
-visualization <sphx_glr_auto_examples_plot_visualization_utils.py>`.
+visualization <sphx_glr_auto_examples_others_plot_visualization_utils.py>`.
 
 .. currentmodule:: torchvision.utils
 

gallery/README.rst

@@ -1,4 +1,2 @@
-Example gallery
-===============
-
-Below is a gallery of examples
+Examples and tutorials
+======================

gallery/others/README.rst

@@ -0,0 +1,2 @@
+Others
+------

gallery/plot_scripted_tensor_transforms.py → gallery/others/plot_scripted_tensor_transforms.py

@@ -58,7 +58,7 @@ def show(imgs):
 # --------------------------
 # Most transforms natively support tensors on top of PIL images (to visualize
 # the effect of the transforms, you may refer to see
-# :ref:`sphx_glr_auto_examples_plot_transforms.py`).
+# :ref:`sphx_glr_auto_examples_others_plot_transforms.py`).
 # Using tensor images, we can run the transforms on GPUs if cuda is available!
 
 import torch.nn as nn

gallery/plot_transforms.py → gallery/others/plot_transforms.py

@@ -19,7 +19,7 @@
 
 
 plt.rcParams["savefig.bbox"] = 'tight'
-orig_img = Image.open(Path('assets') / 'astronaut.jpg')
+orig_img = Image.open(Path('../assets') / 'astronaut.jpg')
 # if you change the seed, make sure that the randomly-applied transforms
 # properly show that the image can be both transformed and *not* transformed!
 torch.manual_seed(0)

gallery/v2_transforms/README.rst

@@ -0,0 +1,2 @@
+V2 transforms
+-------------

gallery/plot_custom_datapoints.py → gallery/v2_transforms/plot_custom_datapoints.py

@@ -6,7 +6,7 @@
 This guide is intended for advanced users and downstream library maintainers. We explain how to
 write your own datapoint class, and how to make it compatible with the built-in
 Torchvision v2 transforms. Before continuing, make sure you have read
-:ref:`sphx_glr_auto_examples_plot_datapoints.py`.
+:ref:`sphx_glr_auto_examples_v2_transforms_plot_datapoints.py`.
 """
 
 # %%

gallery/plot_transforms_v2.py → gallery/v2_transforms/plot_transforms_v2.py

@@ -19,7 +19,7 @@ def load_data():
     from torchvision import datapoints
     from torchvision.ops import masks_to_boxes
 
-    assets_directory = pathlib.Path("assets")
+    assets_directory = pathlib.Path("../assets")
 
     path = assets_directory / "FudanPed00054.png"
     image = datapoints.Image(read_image(str(path)))
@@ -72,9 +72,9 @@ def load_data():
 
 # %%
 # Under the hood, :mod:`torchvision.transforms.v2` relies on :mod:`torchvision.datapoints` for the dispatch to the
-# appropriate function for the input data: :ref:`sphx_glr_auto_examples_plot_datapoints.py`. Note however, that as
+# appropriate function for the input data: :ref:`sphx_glr_auto_examples_v2_transforms_plot_datapoints.py`. Note however, that as
 # regular user, you likely don't have to touch this yourself. See
-# :ref:`sphx_glr_auto_examples_plot_transforms_v2_e2e.py`.
+# :ref:`sphx_glr_auto_examples_v2_transforms_plot_transforms_v2_e2e.py`.
 #
 # All "foreign" types like :class:`str`'s or :class:`pathlib.Path`'s are passed through, allowing to store extra
 # information directly with the sample:

gallery/plot_transforms_v2_e2e.py → gallery/v2_transforms/plot_transforms_v2_e2e.py

@@ -55,7 +55,7 @@ def show(sample):
 def load_example_coco_detection_dataset(**kwargs):
     # This loads fake data for illustration purposes of this example. In practice, you'll have
     # to replace this with the proper data
-    root = pathlib.Path("assets") / "coco"
+    root = pathlib.Path("../assets") / "coco"
     return datasets.CocoDetection(str(root / "images"), str(root / "instances.json"), **kwargs)
 
 

torchvision/datapoints/_datapoint.py

@@ -17,7 +17,7 @@ class Datapoint(torch.Tensor):
 
     You probably don't want to use this class unless you're defining your own
     custom Datapoints. See
-    :ref:`sphx_glr_auto_examples_plot_custom_datapoints.py` for details.
+    :ref:`sphx_glr_auto_examples_v2_transforms_plot_custom_datapoints.py` for details.
     """
 
     @staticmethod

torchvision/transforms/v2/_augment.py

@@ -217,7 +217,7 @@ class MixUp(_BaseMixUpCutMix):
     .. note::
         This transform is meant to be used on **batches** of samples, not
         individual images. See
-        :ref:`sphx_glr_auto_examples_plot_cutmix_mixup.py` for detailed usage
+        :ref:`sphx_glr_auto_examples_v2_transforms_plot_cutmix_mixup.py` for detailed usage
         examples.
         The sample pairing is deterministic and done by matching consecutive
         samples in the batch, so the batch needs to be shuffled (this is an
@@ -267,7 +267,7 @@ class CutMix(_BaseMixUpCutMix):
     .. note::
         This transform is meant to be used on **batches** of samples, not
         individual images. See
-        :ref:`sphx_glr_auto_examples_plot_cutmix_mixup.py` for detailed usage
+        :ref:`sphx_glr_auto_examples_v2_transforms_plot_cutmix_mixup.py` for detailed usage
         examples.
         The sample pairing is deterministic and done by matching consecutive
         samples in the batch, so the batch needs to be shuffled (this is an

torchvision/transforms/v2/functional/_utils.py

@@ -69,7 +69,7 @@ def _name_to_functional(name):
 def register_kernel(functional, datapoint_cls):
     """Decorate a kernel to register it for a functional and a (custom) datapoint type.
 
-    See :ref:`sphx_glr_auto_examples_plot_custom_datapoints.py` for usage
+    See :ref:`sphx_glr_auto_examples_v2_transforms_plot_custom_datapoints.py` for usage
     details.
     """
     if isinstance(functional, str):