Merge pull request #91 from MarcoGorelli/docs-on-support

add docs on support

README.md

@@ -8,18 +8,20 @@
 </h1>
 
 [![PyPI version](https://badge.fury.io/py/narwhals.svg)](https://badge.fury.io/py/narwhals)
-[![Docs](https://img.shields.io/badge/Docs-coolgreen?style=flat&link=https://marcogorelli.github.io/narwhals/)](https://marcogorelli.github.io/narwhals/)
-[![Chat with us! - Join Discord](https://img.shields.io/badge/Chat_with_us!-Join_Discord-coolgreen)](https://discord.gg/V3PqtB4VA4)
 
 Extremely lightweight and extensible compatibility layer between Polars, pandas, Modin, and cuDF (and more!).
 
+- [Read the documentation](https://marcogorelli.github.io/narwhals/)
+- [Chat with us on Discord!](https://discord.gg/V3PqtB4VA4)
+
 Seamlessly support all, without depending on any!
 
 - ✅ **Just use** a subset of **the Polars API**, no need to learn anything new
 - ✅ **No dependencies** (not even Polars), keep your library lightweight
 - ✅ Separate **lazy** and eager APIs
 - ✅ Use **Expressions**
 - ✅ 100% branch coverage, tested against pandas and Polars nightly builds!
+- ✅ Preserve your Index (if present) without it getting in the way!
 
 ## Used by
 

docs/extending.md

@@ -1,14 +1,22 @@
-# How Narwhals can support your dataframe as well!
+# List of supported libraries (and how yours can join this list!)
 
-Currently, Narwhals recognises the following libraries as inputs:
+Currently, Narwhals supports the following libraries as inputs:
 
 - pandas
 - Polars
 - cuDF
 - Modin
 
-If you want your own library to be recognised too, you can either open a PR (with tests) or
-you can make sure that, in addition to the public Narwhals API, you also define:
+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.
+
+## 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`
@@ -25,4 +33,8 @@ you can make sure that, in addition to the public Narwhals API, you also define:
 
   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.PandasDataFrame` does!
+  that's currently what `narwhals._pandas_like.dataframe.PandasDataFrame`, 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 you anything's not clear, or
+doesn't work, please do raise an issue or contact us on Discord (see the link on the README).

docs/index.md

@@ -11,6 +11,7 @@ Seamlessly support both, without depending on either!
 - ✅ Support both **lazy** and eager execution
 - ✅ Use **Expressions**
 - ✅ Tested against pandas and Polars nightly builds!
+- ✅ Preserve your Index (if present) without it getting in the way!
 
 ## Who's this for?
 

mkdocs.yml

@@ -9,7 +9,7 @@ nav:
     - basics/dataframe.md
     - basics/column.md
     - basics/complete_example.md
-  - Extending: extending.md
+  - extending.md
   - Roadmap: roadmap.md
   - Related projects: related.md
   - API Reference: