Create examples showing ndd usage (#6140)

* Add tabs on the front documentation page to show a dynamic mode snippet
* Rework the getting started page for dynamic mode
* Add a way to have dynamic mode variants for notebooks.
* Translate image processing examples to dynamic mode.
* Make pipeline/dynamic mode examples subpages instead of using a button
* Fix links to documentation pages with aliased names
* Move the augmentation gallery dynamic/pipeline mode under the same section
* Fix see also references for dynamic mode
* Translate data loading examples to dynamic mode
* Translate audio processing examples to dynamic mode
* Translate video examples to dynamic mode
* Fix formatting issues
* Fix links to documentation
* Fix copyright headers
* Remove an unused import
* Rework tabs to also support github rendering
* Try the .. container directive to see if GitHub supports it
* Make the dali_tabs extension generate reStructuredText instead of HTML
* Reduce the size of figures in getting started notebooks
* Fix a formatting issue
* Fix an issue with relative synsets imports
* Use absolute paths for operator cross references
* Remove references to pipelines in dynamic mode notebooks
* Fix references to ndd.readers.Numpy in numpy reader example
* Fix the exclusion/inclusion of numpy reader in tests
* Fix title of dynamic/pipeline mode-specific pages and add a badge

---------

Signed-off-by: Rostan Tabet <[email protected]>

Author: rostan-t

.gitignore

@@ -28,16 +28,16 @@ docs/dali.png
 docs/nvidia.ico
 docs/operations/*
 docs/dali_dynamic/operations/*
-docs/examples/audio_processing/index.rst
+docs/examples/audio_processing/**/index.rst
 docs/examples/custom_operations/index.rst
-docs/examples/general/data_loading/index.rst
+docs/examples/general/data_loading/**/index.rst
 docs/examples/general/expressions/index.rst
 docs/examples/general/general_ops_index.rst
-docs/examples/image_processing/index.rst
+docs/examples/image_processing/**/index.rst
 docs/examples/index.rst
 docs/examples/operations_index.rst
 docs/examples/other_index.rst
-docs/examples/sequence_processing/index.rst
+docs/examples/sequence_processing/**/index.rst
 docs/examples/use_cases/index.rst
 docs/examples/use_cases/paddle/index.rst
 .DS_Store

README.rst

@@ -32,63 +32,116 @@ can easily be retargeted to TensorFlow, PyTorch, and PaddlePaddle.
 
 DALI in action:
 
-.. code-block:: python
+.. container:: dali-tabs
 
-  from nvidia.dali.pipeline import pipeline_def
-  import nvidia.dali.types as types
-  import nvidia.dali.fn as fn
-  from nvidia.dali.plugin.pytorch import DALIGenericIterator
-  import os
+   **Pipeline mode:**
 
-  # To run with different data, see documentation of nvidia.dali.fn.readers.file
-  # points to https://github.com/NVIDIA/DALI_extra
-  data_root_dir = os.environ['DALI_EXTRA_PATH']
-  images_dir = os.path.join(data_root_dir, 'db', 'single', 'jpeg')
+   .. code-block:: python
 
+      from nvidia.dali.pipeline import pipeline_def
+      import nvidia.dali.types as types
+      import nvidia.dali.fn as fn
+      from nvidia.dali.plugin.pytorch import DALIGenericIterator
+      import os
 
-  def loss_func(pred, y):
-      pass
+      # To run with different data, see documentation of nvidia.dali.fn.readers.file
+      # points to https://github.com/NVIDIA/DALI_extra
+      data_root_dir = os.environ['DALI_EXTRA_PATH']
+      images_dir = os.path.join(data_root_dir, 'db', 'single', 'jpeg')
 
 
-  def model(x):
-      pass
+      def loss_func(pred, y):
+          pass
 
 
-  def backward(loss, model):
-      pass
+      def model(x):
+          pass
 
 
-  @pipeline_def(num_threads=4, device_id=0)
-  def get_dali_pipeline():
-      images, labels = fn.readers.file(
-          file_root=images_dir, random_shuffle=True, name="Reader")
-      # decode data on the GPU
-      images = fn.decoders.image_random_crop(
-          images, device="mixed", output_type=types.RGB)
-      # the rest of processing happens on the GPU as well
-      images = fn.resize(images, resize_x=256, resize_y=256)
-      images = fn.crop_mirror_normalize(
-          images,
-          crop_h=224,
-          crop_w=224,
-          mean=[0.485 * 255, 0.456 * 255, 0.406 * 255],
-          std=[0.229 * 255, 0.224 * 255, 0.225 * 255],
-          mirror=fn.random.coin_flip())
-      return images, labels
+      def backward(loss, model):
+          pass
 
 
-  train_data = DALIGenericIterator(
-      [get_dali_pipeline(batch_size=16)],
-      ['data', 'label'],
-      reader_name='Reader'
-  )
+      @pipeline_def(num_threads=4, device_id=0)
+      def get_dali_pipeline():
+          images, labels = fn.readers.file(
+              file_root=images_dir, random_shuffle=True, name="Reader")
+          # decode data on the GPU
+          images = fn.decoders.image_random_crop(
+              images, device="mixed", output_type=types.RGB)
+          # the rest of processing happens on the GPU as well
+          images = fn.resize(images, resize_x=256, resize_y=256)
+          images = fn.crop_mirror_normalize(
+              images,
+              crop_h=224,
+              crop_w=224,
+              mean=[0.485 * 255, 0.456 * 255, 0.406 * 255],
+              std=[0.229 * 255, 0.224 * 255, 0.225 * 255],
+              mirror=fn.random.coin_flip())
+          return images, labels
 
 
-  for i, data in enumerate(train_data):
-      x, y = data[0]['data'], data[0]['label']
-      pred = model(x)
-      loss = loss_func(pred, y)
-      backward(loss, model)
+      train_data = DALIGenericIterator(
+          [get_dali_pipeline(batch_size=16)],
+          ['data', 'label'],
+          reader_name='Reader'
+      )
+
+
+      for i, data in enumerate(train_data):
+          x, y = data[0]['data'], data[0]['label']
+          pred = model(x)
+          loss = loss_func(pred, y)
+          backward(loss, model)
+
+   **Dynamic mode:**
+
+   .. code-block:: python
+
+      import os
+      import nvidia.dali.types as types
+      import nvidia.dali.experimental.dynamic as ndd
+      import torch
+
+      # To run with different data, see documentation of ndd.readers.File
+      # points to https://github.com/NVIDIA/DALI_extra
+      data_root_dir = os.environ['DALI_EXTRA_PATH']
+      images_dir = os.path.join(data_root_dir, 'db', 'single', 'jpeg')
+
+
+      def loss_func(pred, y):
+          pass
+
+
+      def model(x):
+          pass
+
+
+      def backward(loss, model):
+          pass
+
+
+      reader = ndd.readers.File(file_root=images_dir, random_shuffle=True)
+
+      for images, labels in reader.next_epoch(batch_size=16):
+          images = ndd.decoders.image_random_crop(images, device="gpu", output_type=types.RGB)
+          # the rest of processing happens on the GPU as well
+          images = ndd.resize(images, resize_x=256, resize_y=256)
+          images = ndd.crop_mirror_normalize(
+              images,
+              crop_h=224,
+              crop_w=224,
+              mean=[0.485 * 255, 0.456 * 255, 0.406 * 255],
+              std=[0.229 * 255, 0.224 * 255, 0.225 * 255],
+              mirror=ndd.random.coin_flip(),
+          )
+
+          x = torch.as_tensor(images)
+          y = torch.as_tensor(labels.gpu())
+
+          pred = model(x)
+          loss = loss_func(pred, y)
+          backward(loss, model)
 
 
 Highlights

docs/_extensions/dali_tabs.py

@@ -0,0 +1,87 @@
+# Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import re
+
+from sphinx.application import Sphinx
+
+# Pattern to match container:: dali-tabs blocks
+CONTAINER_PATTERN = re.compile(
+    r"^\.\. container:: dali-tabs\n((?:[ ]{3,}[^\n]*\n|\n)*)",
+    re.MULTILINE,
+)
+
+# Pattern to match **Tab Name:** headers
+TAB_HEADER_PATTERN = re.compile(r"^[ ]*\*\*([^*]+):\*\*\s*$", re.MULTILINE)
+
+
+def _transform_container_to_tabset(match: re.Match) -> str:
+    """
+    Transform a ``.. container:: dali-tabs`` block into ``.. tab-set::`` RST.
+    See README.rst for an example of usage.
+    """
+    content = match.group(1)
+
+    # Split by tab headers: [before, name1, content1, name2, content2, ...]
+    parts = TAB_HEADER_PATTERN.split(content)
+    if len(parts) < 3:
+        return match.group(0)  # No tabs found, return unchanged
+
+    lines = [".. tab-set::", "   :sync-group: dali-mode", ""]
+
+    for i in range(1, len(parts), 2):
+        tab_name = parts[i].strip()
+        tab_content = parts[i + 1] if i + 1 < len(parts) else ""
+        sync_key = tab_name.lower().replace(" ", "-")
+
+        lines.append(f"   .. tab-item:: {tab_name}")
+        lines.append(f"      :sync: {sync_key}")
+        lines.append("")
+
+        # Re-indent: content has 3-space indent from container, add 3 more for tab-item
+        for line in tab_content.rstrip().split("\n"):
+            if line.strip():
+                lines.append(f"   {line}")
+            else:
+                lines.append("")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def include_read_handler(
+    app: Sphinx,
+    relative_path: str,
+    parent_docname: str,
+    content: list[str],
+) -> None:
+    """Transform container:: dali-tabs in included files."""
+    if not content:
+        return
+
+    text = content[0]
+    if "dali-tabs" not in text:
+        return
+    transformed = CONTAINER_PATTERN.sub(_transform_container_to_tabset, text)
+    if transformed != text:
+        content[0] = transformed
+
+
+def setup(app: Sphinx):
+    app.connect("include-read", include_read_handler)
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/autodoc_submodules.py

@@ -12,13 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import nvidia.dali.plugin.pytorch
-import nvidia.dali.plugin.numba
-import nvidia.dali.plugin.jax
-import nvidia.dali.experimental.dynamic
 import inspect
 import sys
 
+import nvidia.dali.experimental.dynamic
+import nvidia.dali.plugin.jax
+import nvidia.dali.plugin.numba
+import nvidia.dali.plugin.pytorch
+
 try:
     import nvidia.dali.plugin.video
 except ImportError:
@@ -154,7 +155,7 @@ def get_references(name, references):
     if name in references:
         result += ".. seealso::\n"
         for desc, url in references[name]:
-            result += f"   * `{desc} <../{url}>`_\n"
+            result += f"   * `{desc} </{url}>`_\n"
     return result