Make bullet points clickable (#428)

Author: sekyondaMeta

docs/conf.py

@@ -6,9 +6,20 @@
 
 import os
 import sys
+from typing import Callable
+from typing import Protocol
 
 # -- Path setup --------------------------------------------------------------
 
+
+class SphinxApp(Protocol):
+    """Protocol for Sphinx application objects."""
+
+    def connect(self, event: str, callback: Callable[..., None]) -> None:
+        """Connect an event handler to a Sphinx event."""
+        ...
+
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here.
 sys.path.insert(0, os.path.abspath(".."))
@@ -112,3 +123,45 @@
 typehints_fully_qualified = False
 always_document_param_types = True
 typehints_document_rtype = True
+
+
+def remove_sphinx_gallery_content(
+    app: SphinxApp, docname: str, source: list[str]
+) -> None:
+    """
+    Remove sphinx-gallery generated content from the examples index.rst file.
+    This runs after sphinx-gallery generates the file but before the site is built.
+    """
+    if docname == "examples/index":
+        content = source[0]
+
+        # Find the first toctree directive and remove everything after it
+        lines = content.split("\n")
+        new_lines = []
+        found_toctree = False
+
+        for line in lines:
+            if line.strip().startswith(".. toctree::") and not found_toctree:
+                found_toctree = True
+                # Keep the line with the toctree directive
+                new_lines.append(line)
+                # Look for the next few lines that are part of the toctree options
+                continue
+            if found_toctree and (line.strip().startswith(":") or line.strip() == ""):
+                # Keep toctree options and empty lines immediately after
+                new_lines.append(line)
+                continue
+            if found_toctree:
+                # We've hit content after the toctree options, stop here
+                break
+            # Keep everything before the toctree
+            new_lines.append(line)
+
+        # Update the source content
+        source[0] = "\n".join(new_lines)
+
+
+def setup(app: SphinxApp) -> dict[str, str]:
+    """Setup function to register the event handler."""
+    app.connect("source-read", remove_sphinx_gallery_content)
+    return {"version": "0.1"}

examples/README.rst

@@ -7,47 +7,48 @@ The examples are organized into the following categories:
 Basic Operations
 ~~~~~~~~~~~~~~~
 
-- ``add.py``: Element-wise addition with broadcasting support
-- ``exp.py``: Element-wise exponential function
-- ``sum.py``: Sum reduction along the last dimension
-- ``long_sum.py``: Efficient sum reduction along a long dimension
-- ``softmax.py``: Different implementations of the softmax function
+- :doc:`add.py <add>`: Element-wise addition with broadcasting support
+- :doc:`exp.py <exp>`: Element-wise exponential function
+- :doc:`sum.py <sum>`: Sum reduction along the last dimension
+- :doc:`long_sum.py <long_sum>`: Efficient sum reduction along a long dimension
+- :doc:`softmax.py <softmax>`: Different implementations of the softmax function
+
 
 Matrix Multiplication Operations
 ~~~~~~~~~~~~~~~~
 
-- ``matmul.py``: Basic matrix multiplication
-- ``bmm.py``: Batch matrix multiplication
-- ``matmul_split_k.py``: Matrix multiplication using split-K algorithm for better parallelism
-- ``matmul_layernorm.py``: Fused matrix multiplication and layer normalization
-- ``fp8_gemm.py``: Matrix multiplication using FP8 precision
+- :doc:`matmul.py <matmul>`: Basic matrix multiplication
+- :doc:`bmm.py <bmm>`: Batch matrix multiplication
+- :doc:`matmul_split_k.py <matmul_split_k>`: Matrix multiplication using split-K algorithm for better parallelism
+- :doc:`matmul_layernorm.py <matmul_layernorm>`: Fused matrix multiplication and layer normalization
+- :doc:`fp8_gemm.py <fp8_gemm>`: Matrix multiplication using FP8 precision
 
 Attention Operations
 ~~~~~~~~~~~~~~~~~~~
 
-- ``attention.py``: Scaled dot-product attention mechanism
-- ``fp8_attention.py``: Attention mechanism using FP8 precision
+- :doc:`attention.py <attention>`: Scaled dot-product attention mechanism
+- :doc:`fp8_attention.py <fp8_attention>`: Attention mechanism using FP8 precision
 
 Normalization
 ~~~~~~~~~~~~
 
-- ``rms_norm.py``: Root Mean Square (RMS) normalization
+- :doc:`rms_norm.py <rms_norm>`: Root Mean Square (RMS) normalization
 
 Sparse and Jagged Tensors
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- ``jagged_dense_add.py``: Addition between a jagged tensor and a dense tensor
-- ``jagged_mean.py``: Computing the mean of each row in a jagged tensor
-- ``segment_reduction.py``: Segmented reduction operation
-- ``moe_matmul_ogs.py``: Mixture-of-Experts matrix multiplication using Outer-Gather-Scatter
+- :doc:`jagged_dense_add.py <jagged_dense_add>`: Addition between a jagged tensor and a dense tensor
+- :doc:`jagged_mean.py <jagged_mean>`: Computing the mean of each row in a jagged tensor
+- :doc:`segment_reduction.py <segment_reduction>`: Segmented reduction operation
+- :doc:`moe_matmul_ogs.py <moe_matmul_ogs>`: Mixture-of-Experts matrix multiplication using Outer-Gather-Scatter
 
 Other Operations
 ~~~~~~~~~~~~~~~
 
-- ``concatenate.py``: Tensor concatenation along a dimension
-- ``cross_entropy.py``: Cross entropy loss function
-- ``embedding.py``: Embedding lookup operation
-- ``all_gather_matmul.py``: All-gather operation followed by matrix multiplication
+- :doc:`concatenate.py <concatenate>`: Tensor concatenation along a dimension
+- :doc:`cross_entropy.py <cross_entropy>`: Cross entropy loss function
+- :doc:`embedding.py <embedding>`: Embedding lookup operation
+- :doc:`all_gather_matmul.py <all_gather_matmul>`: All-gather operation followed by matrix multiplication
 
 .. toctree::
    :maxdepth: 2