Document the Streamlit extension

and reorganize the documentation

Author: mwouts

README.md

@@ -56,13 +56,12 @@ execute `init_notebook_mode`.
 
 ## Supported environments
 
-`itables` has been tested in the following editors:
-- Jupyter Notebook
-- Jupyter Lab
-- Jupyter nbconvert (i.e. the tables are still interactive in the HTML export of a notebook)
-- Jupyter Book
-- Google Colab
-- VS Code (for both Jupyter Notebooks and Python scripts)
-- PyCharm (for Jupyter Notebooks)
-- Quarto
-- Shiny for Python
+ITables works in all the usual Jupyter Notebook environments, including Jupyter Notebook, Jupyter Lab, Jupyter nbconvert (i.e. the tables are still interactive in the HTML export of a notebook), Jupyter Book, Google Colab and Kaggle.
+
+You can also use ITables in [Quarto](https://mwouts.github.io/itables/quarto.html) HTML documents, and in RISE presentations.
+
+ITables works well in VS Code, both in Jupyter Notebooks and in interactive Python sessions.
+
+Last but not least, ITables is also available in
+[Streamlit](https://mwouts.github.io/itables/streamlit.html) or
+[Shiny](https://mwouts.github.io/itables/shiny.html) applications.

docs/_toc.yml

@@ -1,19 +1,27 @@
 format: jb-book
 root: quick_start
 parts:
-  - caption: How to use DataTables
+  - caption: ITables in Notebooks
     chapters:
     - file: advanced_parameters
-    - file: formatting
     - file: custom_css
+    - file: formatting
+    - file: pandas_style
     - file: extensions
     - file: custom_extensions
-  - caption: ITables
+    - file: quarto
+    - file: downsampling
+    - file: references
+    - file: supported_editors
+  - caption: ITables in Applications
+    chapters:
+      - file: html_export
+      - file: dash
+      - file: shiny
+      - file: streamlit
+      - file: ipywidgets
+  - caption: Contributing to ITables
     chapters:
-      - file: supported_editors
-      - file: quarto
-      - file: downsampling
-      - file: references
       - file: contributing
       - file: developing
       - file: troubleshooting
@@ -22,4 +30,3 @@ parts:
     chapters:
     - file: sample_dataframes
     - file: polars_dataframes
-    - file: pandas_style

docs/advanced_parameters.md

@@ -12,7 +12,7 @@ kernelspec:
   name: itables
 ---
 
-# The DataTables Arguments
+# Advanced Parameters
 
 ITables is a wrapper for the Javascript [DataTables](https://datatables.net/) library, which has a great [documentation](https://datatables.net/), a huge collection of [examples](https://datatables.net/examples/index), and a useful [forum](https://datatables.net/forums/).
 

docs/contributing.md

@@ -1,29 +1,72 @@
+---
+jupytext:
+  formats: md:myst
+  notebook_metadata_filter: -jupytext.text_representation.jupytext_version
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+kernelspec:
+  display_name: itables
+  language: python
+  name: itables
+---
+
 # Contributing
 
 Thanks for considering making a contribution to ITables. There are
-indeed many ways to help!
+many ways you can help!
 
-## Reporting an issue
+## Report an issue
 
 If you see an issue, a possible improvement, or if you can't find
 the answer to your question, then you are very welcome to create
 an issue on this project. Please provide enough detail so that
 we can reproduce the issue.
 
-## Improving the documentation
+## Improve the documentation
 
 If you would like to add a new example,
 or improve the documentation, feel free to make a pull request!
 
 You can render the documentation locally - see the section on
 [Jupyter Book](developing.md#jupyter-book) in the developer guide.
 
-## Developing a new feature
+## Give credit to ITables
+
+It's always great to see new stars coming to ITables! <a class="github-button" href="https://github.com/mwouts/itables" data-icon="octicon-star" data-show-count="true"></a>
+<script src="https://buttons.github.io/buttons.js"></script>
+
+If you wanted to share a link to ITables and DataTables (no obligation whatsoever), you could use something like this:
+
+```{code-cell}
+from IPython.display import HTML, display
+
+display(
+    HTML(
+        """
+Tables displayed with <a href=https://mwouts.github.io/itables/>ITables</a>,
+a Python wrapper for <a href=https://datatables.net>DataTables</a>
+"""
+    )
+)
+```
+
+## Support DataTables
+
+Allan Jardine, the main developer of DataTables, has done a fantastic work on [DataTables](https://datatables.net/).
+
+If you enjoy his library, you could become a
+[supporter](https://datatables.net/supporters/) -
+contributions range from 9 to 99$/year before VAT.
+Or you could take a subscription for DataTable's [Editor](https://editor.datatables.net)
+that ITables might support in the future (please subscribe to [#243](https://github.com/mwouts/itables/issues/243) for updates).
+
+## Develop a new feature
 
 It is generally a good idea to get in touch with us first - e.g.
 open an issue and let us know what you'd like to do.
 
 But you can also simply clone the project and test your ideas.
-
 A guide on how to set up a development environment, and how to
 run some tests, is available [here](developing.md).

docs/custom_css.md

@@ -12,7 +12,7 @@ kernelspec:
   name: itables
 ---
 
-# Styling
+# Table Style and CSS
 
 As usual, we initialize ITables with `init_notebook_mode`, and we create two sample DataFrames:
 
@@ -113,7 +113,7 @@ show(df, classes="display nowrap table_with_monospace_font")
 The `show` function has a `style` argument that determines the
 style for that particular table.
 
-The default value for `style` is `table-layout:auto;width:auto;margin:auto;caption-side:bottom`.
+The default value for `style` is `"table-layout:auto;width:auto;margin:auto;caption-side:bottom"`. When `scrollX` is `True`, `margin:auto` gets replaced with `margin:0` to avoid misaligned headers.
 Without `width:auto`, tables with few columns still take the full notebook width in Jupyter.
 Using `margin:auto` makes non-wide tables centered in Jupyter.
 

docs/dash.md

@@ -0,0 +1,4 @@
+# Dash
+
+ITables does not have a [Dash](https://dash.plotly.com/) component, but might get one in the future.
+You are welcome to subscribe or contribute to [#245](https://github.com/mwouts/itables/issues/245).

docs/extensions.md

@@ -12,7 +12,7 @@ kernelspec:
   name: itables
 ---
 
-# DataTables Extensions
+# Download Buttons and Other Extensions
 
 DataTables comes with a series of [extensions](https://datatables.net/extensions/), which are supported by ITables since v2.0.
 A selection of these extensions are included in ITables.
@@ -102,6 +102,11 @@ show(
 )
 ```
 
+```{warning}
+At the moment, the CSV and Excel buttons don't work well with large tables in some browsers.
+Please subscribe to [#251](https://github.com/mwouts/itables/issues/251) if you wish to receive updates on this.
+```
+
 ```{warning}
 The PDF button is not included in ITables' DataTable bundle. This is because the required PDF libraries
 have a large footprint on the bundle size. Still, you can add it to your custom bundle, see the next chapter.

docs/formatting.md

@@ -12,7 +12,7 @@ kernelspec:
   name: itables
 ---
 
-# Formatting
+# Cell Formatting
 
 ## Formatting with Pandas
 

docs/html_export.md

@@ -0,0 +1,41 @@
+---
+jupytext:
+  formats: md:myst
+  notebook_metadata_filter: -jupytext.text_representation.jupytext_version
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+kernelspec:
+  display_name: itables
+  language: python
+  name: itables
+---
+
+# HTML export
+
+To get the HTML representation of a Pandas DataFrame `df` as an interactive [DataTable](https://datatables.net/), you can use `to_html_datatable` as below:
+
+```{code-cell}
+from IPython.display import HTML, display
+
+from itables import to_html_datatable
+from itables.sample_dfs import get_countries
+
+df = get_countries(html=False)
+html = to_html_datatable(df.head(3), display_logo_when_loading=False)
+```
+
+You can then save the `html` variable to a text file (note: if you're writing an HTML application, you could consider using [Shiny](shiny.md) or [Streamlit](streamlit.md) instead), or print it:
+
+```{code-cell}
+:tags: [scroll-output]
+
+print(html)
+```
+
+or display it, like `show` does:
+
+```{code-cell}
+display(HTML(html))
+```

docs/ipywidgets.md

@@ -0,0 +1,4 @@
+# IPyWidgets
+
+ITables does not come as a [Jupyter Widget](https://ipywidgets.readthedocs.io) at the moment.
+You are welcome to subscribe or contribute to [#267](https://github.com/mwouts/itables/issues/267).