Document the Streamlit extension

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).

docs/pandas_style.md

@@ -12,11 +12,26 @@ kernelspec:
   name: itables
 ---
 
-# Pandas Style examples
+# Using Pandas Style
 
 Starting with `itables>=1.6.0`, ITables provides support for
 [Pandas Style](https://pandas.pydata.org/docs/user_guide/style.html).
 
+```{note}
+Unlike Pandas or Polar DataFrames, `Styler` objects are rendered directly using their
+`to_html` method, rather than passing the underlying table data to the DataTables
+library.
+
+Because of this, the rendering of the table might differ slightly from the rendering of the
+corresponding DataFrame. In particular,
+- The downsampling is not available - please pay attention to the size of the table being rendered
+- Sorting of numbers will not work if the column contains NaNs.
+```
+
+```{warning}
+Pandas Style objects can't be used with the [Streamlit extension](streamlit.md) for ITables.
+```
+
 ```{code-cell}
 import numpy as np
 import pandas as pd
@@ -83,14 +98,3 @@ ttips = pd.DataFrame(
 )
 s.set_tooltips(ttips).set_caption("With tooltips")
 ```
-
-```{note}
-Unlike Pandas or Polar DataFrames, `Styler` objects are rendered directly using their
-`to_html` method, rather than passing the underlying table data to the DataTables
-library.
-
-Because of this, the rendering of the table might differ slightly from the rendering of the
-corresponding DataFrame. In particular,
-- The downsampling is not available - please pay attention to the size of the table being rendered
-- Sorting of numbers will not work if the column contains NaNs.
-```

docs/quarto.md

@@ -1,17 +1,3 @@
----
-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
----
-
 # Quarto
 
 ITables works well with the `revealjs` and `html` outputs formats of [Quarto](https://quarto.org).

docs/quick_start.md

@@ -20,8 +20,8 @@ kernelspec:
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/itables.svg)](https://anaconda.org/conda-forge/itables)
 [![pyversions](https://img.shields.io/pypi/pyversions/itables.svg)](https://pypi.python.org/pypi/itables)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-<a class="github-button" href="https://github.com/mwouts/itables" data-icon="octicon-star" data-show-count="true" aria-label="Star mwouts/itables on GitHub">Star</a>
-<script async defer src="https://buttons.github.io/buttons.js"></script>
+<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>
 
 This packages changes how Pandas and Polars DataFrames are rendered in Jupyter Notebooks.
 With `itables` you can display your tables as interactive [DataTables](https://datatables.net/)
@@ -49,9 +49,9 @@ or
 conda install itables -c conda-forge
 ```
 
-## Activate ITables
+## Activate ITables in a Notebook
 
-Activate the interactive mode for all series and dataframes with
+Activate the interactive mode in notebook-like environment with `init_notebook_mode`:
 
 ```{code-cell}
 from itables import init_notebook_mode
@@ -70,6 +70,16 @@ df = get_countries(html=False)
 df
 ```
 
+If you prefer to render only certain tables using `itables`, or want
+to pass [advanced parameters](advanced_parameters.md) along with the
+DataFrame, use `show`:
+
+```{code-cell}
+from itables import show
+
+show(df, lengthMenu=[2, 5, 10, 25, 50, 100, 250])
+```
+
 ## Offline mode versus connected mode
 
 ITables use two Javascript libraries:
@@ -85,17 +95,6 @@ To do so, add the argument `connected=True` when you
 execute `init_notebook_mode`. This will also make your notebook lighter by
 about [700kB](https://github.com/mwouts/itables/blob/main/tests/test_connected_notebook_is_small.py).
 
-## Using ITables for specific tables only
-
-If you prefer to render only certain series or dataframes using `itables`,
-then call `init_notebook_mode(all_interactive=False)` then `show`:
-
-```{code-cell}
-from itables import show
-
-show(df, lengthMenu=[2, 5, 10, 25, 50, 100, 250])
-```
-
 ## Try ITables on Binder
 
-You can run our examples notebooks directly on [![Lab](https://img.shields.io/badge/Binder-JupyterLab-blue.svg)](https://mybinder.org/v2/gh/mwouts/itables/main?urlpath=lab/tree/docs/quick_start.md), without having to install anything on your side.
+You can run the examples above (or any other documentation page) directly on ![Lab](https://img.shields.io/badge/Binder-JupyterLab-blue.svg), without having to install anything on your end - just click on the rocket icon at the top of the page.

docs/shiny.md

@@ -0,0 +1,14 @@
+# Shiny
+
+You can use ITables in Web applications generated with [Shiny](https://shiny.rstudio.com/py/) for Python with e.g.
+```python
+from shiny import ui
+
+from itables.sample_dfs import get_countries
+from itables.shiny import DT
+
+df = get_countries(html=False)
+ui.HTML(DT(df))
+```
+
+See also our [tested examples](https://github.com/mwouts/itables/tree/main/tests/sample_python_apps).