From c572180ebc7d876714a38688c53f7e4af87abd93 Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Sat, 9 Nov 2024 16:59:10 +0000
Subject: [PATCH] docs: Fill out `Loader.url`

---
 altair/datasets/__init__.py | 40 +++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/altair/datasets/__init__.py b/altair/datasets/__init__.py
index 260258882..b7f87bdaa 100644
--- a/altair/datasets/__init__.py
+++ b/altair/datasets/__init__.py
@@ -143,7 +143,6 @@ def __call__(
         """Get a remote dataset and load as tabular data."""
         return self._reader.dataset(name, suffix, tag=tag, **kwds)
 
-    # TODO: docs (parameters, examples)
     def url(
         self,
         name: DatasetName | LiteralString,
@@ -151,7 +150,44 @@ def url(
         /,
         tag: VersionTag | None = None,
     ) -> str:
-        """Return the address of a remote dataset."""
+        """
+        Return the address of a remote dataset.
+
+        Parameters
+        ----------
+        name
+            Name of the dataset/`stem`_ of filename.
+        suffix
+            File extension/`Path.suffix`_.
+
+            .. note::
+                Only needed if ``name`` is available in multiple formats.
+        tag
+            `vega-datasets release`_ version.
+
+        .. _stem:
+            https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.stem
+        .. _Path.suffix:
+            https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.suffix
+        .. _vega-datasets release:
+            https://github.com/vega/vega-datasets/releases
+
+        Examples
+        --------
+        The returned url will always point to an accessible dataset:
+
+            import altair as alt
+            from altair.datasets import Loader
+
+            data = Loader.with_backend("polars")
+            data.url("cars", tag="v2.9.0")
+            'https://cdn.jsdelivr.net/npm/vega-datasets@v2.9.0/data/cars.json'
+
+        We can pass the result directly to a chart:
+
+            url = data.url("cars", tag="v2.9.0")
+            alt.Chart(url).mark_point().encode(x="Horsepower:Q", y="Miles_per_Gallon:Q")
+        """
         return self._reader.url(name, suffix, tag=tag)
 
     @property