docs: update docstrings for dataframe.schema (#276)

* update-dataframe-lazyframe docstring-batch3

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* resolved conflict

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* included output for both dataframe usecase

* minor edit

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

narwhals/dataframe.py

@@ -353,6 +353,8 @@ def shape(self) -> tuple[int, int]:
         Get the shape of the DataFrame.
 
         Examples:
+            Construct pandas and polars DataFrames:
+
             >>> import pandas as pd
             >>> import polars as pl
             >>> import narwhals as nw
@@ -526,6 +528,8 @@ def with_row_index(self, name: str = "index") -> Self:
         Insert column which enumerates rows.
 
         Examples:
+            Construct pandas as polars DataFrames:
+
             >>> import polars as pl
             >>> import pandas as pd
             >>> import narwhals as nw
@@ -568,17 +572,32 @@ def schema(self) -> dict[str, DType]:
 
         Examples:
             >>> import polars as pl
+            >>> import pandas as pd
             >>> import narwhals as nw
-            >>> df_pl = pl.DataFrame(
-            ...     {
+            >>> data = {
             ...         "foo": [1, 2, 3],
             ...         "bar": [6.0, 7.0, 8.0],
             ...         "ham": ["a", "b", "c"],
             ...     }
-            ... )
-            >>> df = nw.DataFrame(df_pl)
-            >>> df.schema  # doctest: +SKIP
-            OrderedDict({'foo': Int64, 'bar': Float64, 'ham': String})
+            >>> df_pd = pd.DataFrame(data)
+            >>> df_pl = pl.DataFrame(data)
+
+            We define a library agnostic function:
+
+            >>> def func(df_any):
+            ...     df = nw.from_native(df_any)
+            ...     return df.schema
+
+            You can pass either pandas or Polars to `func`:
+
+            >>> df_pd_schema = func(df_pd)
+            >>> df_pd_schema
+            {'foo': Int64, 'bar': Float64, 'ham': String}
+
+            >>> df_pl_schema = func(df_pl)
+            >>> df_pl_schema
+            {'foo': Int64, 'bar': Float64, 'ham': String}
+
         """
         return super().schema
 
@@ -645,7 +664,7 @@ def with_columns(
             ...         "c": [True, True, False, True],
             ...     }
             ... )
-            >>> df = nw.DataFrame(df_pl)
+            >>> df = nw.from_native(df_pl)
             >>> dframe = df.with_columns((nw.col("a") * 2).alias("a*2"))
             >>> dframe
             ┌───────────────────────────────────────────────┐