update docs (#1109)

narwhals-dev · Oct 1, 2024 · 9b4e5ab · 9b4e5ab
1 parent 9cd953e
commit 9b4e5ab
Show file tree

Hide file tree

Showing 5 changed files with 59 additions and 58 deletions.
diff --git a/README.md b/README.md
@@ -13,11 +13,12 @@
 Extremely lightweight and extensible compatibility layer between dataframe libraries!
 
 - **Full API support**: cuDF, Modin, pandas, Polars, PyArrow
+- **Lazy-only support**: Dask
 - **Interchange-level support**: Ibis, Vaex, anything else which implements the DataFrame Interchange Protocol
 
 Seamlessly support all, without depending on any!
 
-- ✅ **Just use** a subset of **the Polars API**, no need to learn anything new
+- ✅ **Just use** [a subset of **the Polars API**](https://narwhals-dev.github.io/narwhals/api-reference/), no need to learn anything new
 - ✅ **Zero dependencies**, Narwhals only uses what
   the user passes in so your library can stay lightweight
 - ✅ Separate **lazy** and eager APIs, use **expressions**
@@ -117,6 +118,9 @@ Narwhals has been featured in several talks, podcasts, and blog posts:
 - [Talk Python to me Podcast](https://youtu.be/FSH7BZ0tuE0)
   Ahoy, Narwhals are bridging the data science APIs
 
+- [Python Bytes Podcast](https://www.youtube.com/live/N7w_ESVW40I?si=y-wN1uCsAuJOKlOT&t=382)
+  Ahoy, Narwhals are bridging the data science APIs
+
 - [Super Data Science: ML & AI Podcast](https://www.youtube.com/watch?v=TeG4U8R0U8U)  
   Narwhals: For Pandas-to-Polars DataFrame Compatibility
 

diff --git a/docs/css/mkdocstrings.css b/docs/css/mkdocstrings.css
diff --git a/docs/extending.md b/docs/extending.md
@@ -2,7 +2,7 @@
 
 ## List of supported libraries (and how to add yours!)
 
-Currently, Narwhals supports the following libraries as inputs:
+Currently, Narwhals has full API support for the following libraries:
 
 | Library  | 🔗 Link 🔗 |
 | ------------- | ------------- |
@@ -12,46 +12,13 @@ Currently, Narwhals supports the following libraries as inputs:
 | Modin | [github.com/modin-project/modin](https://github.com/modin-project/modin) |
 | PyArrow ⇶ | [arrow.apache.org/docs/python](https://arrow.apache.org/docs/python/index.html) |
 
-If you want your own library to be recognised too, you're welcome open a PR (with tests)!
-Alternatively, if you can't do that (for example, if you library is closed-source), see
-the next section for what else you can do.
-
-To check which methods are supported for which backend in depth, please refer to the
-[API completeness page](api-completeness/index.md).
-
-## Extending Narwhals
-
-We love open source, but we're not "open source absolutists". If you're unable to open
-source you library, then this is how you can make your library compatible with Narwhals.
-
-Make sure that, in addition to the public Narwhals API, you also define:
-
-  - `DataFrame.__narwhals_dataframe__`: return an object which implements public methods
-    from `Narwhals.DataFrame`
-  - `DataFrame.__narwhals_namespace__`: return an object which implements public top-level
-    functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...)
-  - `DataFrame.__native_namespace__`: return a native namespace object which must have a
-    `from_dict` method
-  - `LazyFrame.__narwhals_lazyframe__`: return an object which implements public methods
-    from `Narwhals.LazyFrame`
-  - `LazyFrame.__narwhals_namespace__`: return an object which implements public top-level
-    functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...)
-  - `LazyFrame.__native_namespace__`: return a native namespace object which must have a
-    `from_dict` method
-  - `Series.__narwhals_series__`: return an object which implements public methods
-    from `Narwhals.Series`
-
-  If your library doesn't distinguish between lazy and eager, then it's OK for your dataframe
-  object to implement both `__narwhals_dataframe__` and `__narwhals_lazyframe__`. In fact,
-  that's currently what `narwhals._pandas_like.dataframe.PandasLikeDataFrame` does. So, if you're stuck,
-  take a look at the source code to see how it's done!
-
-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).
+It also has lazy-only support for [Dask](https://github.com/dask/dask), and interchange-only support
+for [DuckDB](https://github.com/duckdb/duckdb) and [Ibis](https://github.com/ibis-project/ibis).
 
-## Levels
+### Levels
 
-Narwhals comes with two levels of support: "full" and "interchange".
+Narwhals comes with two levels of support ("full" and "interchange"), and we are working on defining
+a "lazy-only" level too.
 
 Libraries for which we have full support can benefit from the whole
 [Narwhals API](https://narwhals-dev.github.io/narwhals/api-reference/).
@@ -91,4 +58,38 @@ def func(df: Any) -> Schema:
     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.
+also pass Ibis, DuckDB, Vaex, and any library which implements the protocol.
+
+### Extending Narwhals
+
+If you want your own library to be recognised too, you're welcome open a PR (with tests)!.
+Alternatively, if you can't do that (for example, if you library is closed-source), see
+the next section for what else you can do.
+
+We love open source, but we're not "open source absolutists". If you're unable to open
+source you library, then this is how you can make your library compatible with Narwhals.
+
+Make sure that, in addition to the public Narwhals API, you also define:
+
+  - `DataFrame.__narwhals_dataframe__`: return an object which implements public methods
+    from `Narwhals.DataFrame`
+  - `DataFrame.__narwhals_namespace__`: return an object which implements public top-level
+    functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...)
+  - `DataFrame.__native_namespace__`: return a native namespace object which must have a
+    `from_dict` method
+  - `LazyFrame.__narwhals_lazyframe__`: return an object which implements public methods
+    from `Narwhals.LazyFrame`
+  - `LazyFrame.__narwhals_namespace__`: return an object which implements public top-level
+    functions from `narwhals` (e.g. `narwhals.col`, `narwhals.concat`, ...)
+  - `LazyFrame.__native_namespace__`: return a native namespace object which must have a
+    `from_dict` method
+  - `Series.__narwhals_series__`: return an object which implements public methods
+    from `Narwhals.Series`
+
+  If your library doesn't distinguish between lazy and eager, then it's OK for your dataframe
+  object to implement both `__narwhals_dataframe__` and `__narwhals_lazyframe__`. In fact,
+  that's currently what `narwhals._pandas_like.dataframe.PandasLikeDataFrame` does. So, if you're stuck,
+  take a look at the source code to see how it's done!
+
+Note that this "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).
diff --git a/docs/index.md b/docs/index.md
@@ -2,11 +2,15 @@
 
 ![](assets/image.png)
 
-Extremely lightweight compatibility layer between Polars, pandas, and more.
+Extremely lightweight and extensible compatibility layer between dataframe libraries!
 
-Seamlessly support both, without depending on either!
+- **Full API support**: cuDF, Modin, pandas, Polars, PyArrow
+- **Lazy-only support**: Dask
+- **Interchange-level support**: Ibis, Vaex, anything else which implements the DataFrame Interchange Protocol
 
-- ✅ **Just use** a subset of **the Polars API**, no need to learn anything new
+Seamlessly support all, without depending on any!
+
+- ✅ **Just use** [a subset of **the Polars API**](https://narwhals-dev.github.io/narwhals/api-reference/), no need to learn anything new
 - ✅ **Zero dependencies**, Narwhals only uses what
   the user passes in so your library can stay lightweight
 - ✅ Separate **lazy** and eager APIs, use **expressions**

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -19,11 +19,12 @@ nav:
   - extending.md
   - how_it_works.md
   - Roadmap and related projects: roadmap_and_related.md
-  - API Completeness:
-    - api-completeness/index.md
-    - Supported DataFrame methods: api-completeness/dataframe.md
-    - Supporteda Expr methods: api-completeness/expr.md
-    - Supported Series methods: api-completeness/series.md
+  # Commented-out until https://github.com/narwhals-dev/narwhals/issues/1004 is addressed
+  # - API Completeness:
+  #   - api-completeness/index.md
+  #   - Supported DataFrame methods: api-completeness/dataframe.md
+  #   - Supported Expr methods: api-completeness/expr.md
+  #   - Supported Series methods: api-completeness/series.md
   - API Reference:
     - api-reference/narwhals.md
     - api-reference/dataframe.md