docs: Restructure docs a bit (#1007)

* restructure docs a bit * missing file * fix link
narwhals-dev · Sep 20, 2024 · 8b2b30b · 8b2b30b
1 parent f0b31ee
commit 8b2b30b
Show file tree

Hide file tree

Showing 9 changed files with 144 additions and 150 deletions.
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/extending.md b/docs/extending.md
@@ -1,4 +1,6 @@
-# List of supported libraries (and how to add yours!)
+# Extending Narwhals, levels of support
+
+## List of supported libraries (and how to add yours!)
 
 Currently, Narwhals supports the following libraries as inputs:
 
@@ -44,3 +46,47 @@ Make sure that, in addition to the public Narwhals API, you also define:
 
 Note that the "extension" mechanism is still experimental. If anything is not clear, or
 doesn't work, please do raise an issue or contact us on Discord (see the link on the README).
+
+## Levels
+
+Narwhals comes with two levels of support: "full" and "interchange".
+
+Libraries for which we have full support can benefit from the whole
+[Narwhals API](https://narwhals-dev.github.io/narwhals/api-reference/).
+
+For example:
+
+```python exec="1" source="above"
+import narwhals as nw
+from narwhals.typing import FrameT
+
+
+@nw.narwhalify
+def func(df: FrameT) -> FrameT:
+    return df.group_by("a").agg(
+        b_mean=nw.col("b").mean(),
+        b_std=nw.col("b").std(),
+    )
+```
+will work for any of pandas, Polars, cuDF, Modin, and PyArrow.
+
+However, sometimes you don't need to do complex operations on dataframes - all you need
+is to inspect the schema a bit before making other decisions, such as which columns to
+select or whether to convert to another library. For that purpose, we also provide "interchange"
+level of support. If a library implements the
+[Dataframe Interchange Protocol](https://data-apis.org/dataframe-protocol/latest/), then
+a call such as
+
+```python exec="1" source="above"
+from typing import Any
+
+import narwhals as nw
+from narwhals.schema import Schema
+
+
+def func(df: Any) -> Schema:
+    df = nw.from_native(df, eager_or_interchange_only=True)
+    return df.schema
+```
+is also supported, meaning that, in addition to the libraries mentioned above, you can
+also pass Ibis, Vaex, PyArrow, and any other library which implements the protocol.
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 [extending](extending.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,8 +5,7 @@ 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
@@ -15,18 +14,16 @@ nav:
     - other/pandas_index.md
     - other/user_warning.md
     - other/column_names.md
-  - levels.md
   - overhead.md
   - backcompat.md
   - extending.md
   - how_it_works.md
-  - Roadmap: roadmap.md
-  - Related projects: related.md
+  - Roadmap and related projects: roadmap_and_related.md
   - API Completeness:
     - 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 Reference:
     - api-reference/narwhals.md
     - api-reference/dataframe.md