narwhals-dev · MarcoGorelli · Sep 17, 2024 · Sep 17, 2024 · FBruzzesi · Sep 17, 2024
diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md
@@ -1,30 +1,20 @@
 # API Reference
 
-Anything documented in the API reference is intended to work consistently among
-supported backends.
-
-For example:
-```python
-import narwhals as nw
-
-df.with_columns(
-    a_mean=nw.col("a").mean(),
-    a_std=nw.col("a").std(),
-)
-```
-is supported, as `DataFrame.with_columns`, `narwhals.col`, `Expr.mean`, and `Expr.std` are
-all documented in the API reference.
-
-However,
-```python
-import narwhals as nw
-
-df.with_columns(
-    a_ewm_mean=nw.col("a").ewm_mean(alpha=0.7),
-)
-```
-is not - `Expr.ewm_mean` only appears in the Polars API reference, but not in the Narwhals
-one.
-
-In general, you should expect any fundamental dataframe operation to be supported - if
-one that you need is not, please do open a feature request!
+- [Top-level functions](narwhals.md)
+- [narwhals.DataFrame](dataframe.md)
+- [narwhals.Expr](expr.md)
+- [narwhals.Expr.cat](expr_cat.md)
+- [narwhals.Expr.dt](expr_dt.md)
+- [narwhals.Expr.name](expr_name.md)
+- [narwhals.Expr.str](expr_str.md)
+- [narwhals.GroupBy](group_by.md)
+- [narwhals.LazyFrame](lazyframe.md)
+- [narwhals.Schema](schema.md)
+- [narwhals.Series](series.md)
+- [narwhals.Series.cat](series_cat.md)
+- [narwhals.Series.dt](series_dt.md)
+- [narwhals.Series.str](series_str.md)
+- [narwhals.dependencies](dependencies.md)
+- [narwhals.dtypes](dtypes.md)
+- [narwhals.selectors](selectors.md)
+- [narwhals.typing](typing.md)
diff --git a/docs/other/column_names.md → docs/coming_from_pandas/column_names.md b/docs/other/column_names.md → docs/coming_from_pandas/column_names.md
diff --git a/docs/extending.md → docs/coming_from_pandas/extending.md b/docs/extending.md → docs/coming_from_pandas/extending.md
diff --git a/docs/overhead.md → docs/coming_from_pandas/overhead.md b/docs/overhead.md → docs/coming_from_pandas/overhead.md
diff --git a/docs/other/pandas_index.md → docs/coming_from_pandas/pandas_index.md b/docs/other/pandas_index.md → docs/coming_from_pandas/pandas_index.md
diff --git a/docs/other/user_warning.md → docs/coming_from_pandas/user_warning.md b/docs/other/user_warning.md → docs/coming_from_pandas/user_warning.md
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,4 +1,6 @@
-# Installation
+# Installation and quick start
+
+## Installation
 
 First, make sure you have [created and activated](https://docs.python.org/3/library/venv.html) a Python3.8+ virtual environment.
 
@@ -14,3 +16,49 @@ Then, if you start the Python REPL and see the following:
 '1.8.1'
 ```
 then installation worked correctly!
+
+## Quick start
+
+### Prerequisites
+
+Please start by following the [installation instructions](installation.md).
+
+To follow along with the examples which follow, please install the following (though note that
+they are not required dependencies - Narwhals only ever uses what the user passes in):
+
+- [pandas](https://pandas.pydata.org/docs/getting_started/install.html)
+- [Polars](https://pola-rs.github.io/polars/user-guide/installation/)
+
+### Simple example
+
+Create a Python file `t.py` with the following content:
+
+```python exec="1" source="above" session="quickstart" result="python"
+from __future__ import annotations
+
+import pandas as pd
+import polars as pl
+import narwhals as nw
+from narwhals.typing import IntoFrame
+
+
+def my_function(df_native: IntoFrame) -> list[str]:
+    df = nw.from_native(df_native)
+    column_names = df.columns
+    return column_names
+
+
+df_pandas = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+df_polars = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+
+print("pandas output")
+print(my_function(df_pandas))
+print("Polars output")
+print(my_function(df_polars))
+```
+
+If you run `python t.py` then your output should look like the above. This is the simplest possible example of a dataframe-agnostic
+function - as we'll soon see, we can do much more advanced things.
+Let's learn about what you just did, and what Narwhals can do for you!
+
+Note: these examples are only using pandas and Polars. Please see the following to find the [supported libriaries](extending.md).
diff --git a/docs/levels.md b/docs/levels.md
diff --git a/docs/quick_start.md b/docs/quick_start.md
diff --git a/docs/related.md b/docs/related.md
diff --git a/docs/roadmap.md b/docs/roadmap.md
diff --git a/docs/roadmap_and_related.md b/docs/roadmap_and_related.md
@@ -0,0 +1,25 @@
+# Roadmap and related projects
+
+## Roadmap
+
+Priorities, as of September 2024, are:
+
+- Works towards supporting projects which have shown interest in Narwhals.
+- Add extra docs and tutorials to make the project more accessible and easy to get started with.
+- Improve support for cuDF, which we can't currently test in CI (unless NVIDIA helps us out :wink:) but
+  which we can and do test manually in Kaggle notebooks.
+- Define a lazy-only layer of support which can include DuckDB, Ibis, and PySpark.
+
+## Related projects
+
+### Dataframe Interchange Protocol
+
+Standardised way of interchanging data between libraries, see
+[here](https://data-apis.org/dataframe-protocol/latest/index.html).
+
+Narwhals builds upon it by providing one level of support to libraries which implement it -
+this includes Ibis and Vaex. See [levels](levels.md) for details.
+
+### Array API
+
+Array counterpart to the DataFrame API, see [here](https://data-apis.org/array-api/2022.12/index.html).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -5,28 +5,26 @@ watch:
 nav:
   - Home: index.md
   - Why: why.md
-  - Installation: installation.md
-  - Quick start: quick_start.md
+  - Installation and quick start: installation.md
   - Tutorial:
     - basics/dataframe.md
     - basics/column.md
     - basics/complete_example.md
-  - Pandas-like concepts:
-    - other/pandas_index.md
-    - other/user_warning.md
-    - other/column_names.md
-  - levels.md
-  - overhead.md
+  - Coming from pandas:
+    - coming_from_pandas/pandas_index.md
+    - coming_from_pandas/user_warning.md
+    - coming_from_pandas/column_names.md
+    - coming_from_pandas/overhead.md
   - backcompat.md
-  - extending.md
   - how_it_works.md
-  - Roadmap: roadmap.md
-  - Related projects: related.md
-  - API Completeness:
+  - Roadmap and related projects: roadmap.md
+  - Supported libraries:
     - api-completeness/index.md
-    - api-completeness/dataframe.md
-    - api-completeness/expr.md
-    - api-completeness/series.md
+    - Supported DataFrame methods: api-completeness/dataframe.md
+    - Supporteda Expr methods: api-completeness/expr.md
+    - Supported Series methods: api-completeness/series.md
+    - api-completeness/levels.md
+    - api-completeness/extending.md
   - API Reference:
     - api-reference/narwhals.md
     - api-reference/dataframe.md