Use full width, update examples

Author: mwouts

docs/apps/notebook.md

@@ -12,6 +12,12 @@ kernelspec:
   name: itables
 ---
 
+```{code-cell} ipython3
+:tags: [remove-cell]
+
+# pyright: reportUnusedExpression=false
+```
+
 # Notebook Mode
 
 Activate ITables in a Jupyter environment for all your tables with `init_notebook_mode`:
@@ -24,6 +30,13 @@ itables.init_notebook_mode()
 
 You can go back to the standard HTML representation of Pandas DataFrames with `init_notebook_mode(all_interactive=False)`.
 
+```{code-cell} ipython3
+:tags: [full-width]
+
+df = itables.sample_dfs.get_countries(html=False)
+df
+```
+
 Note that the `init_connected_mode` function also activates ITable's offline mode, unless you call it with a `connected=False` argument.
 
 
@@ -42,15 +55,7 @@ about [700kB](https://github.com/mwouts/itables/blob/main/tests/test_connected_n
 If you prefer to render only certain tables using `itables`, or want to set additional options, use `show`:
 
 ```{code-cell} ipython3
-df = itables.sample_dfs.get_countries(html=False)
+:tags: [full-width]
 
-itables.show(
-    df,
-    caption="A DataFrame rendered with ITables",
-    lengthMenu=[2, 5, 10, 25, 50, 100, 250],
-)
+itables.show(df, caption="A DataFrame rendered with ITables")
 ```
-
-## HTML
-
-The `show` function simply displays the HTML snippet for the table, which is obtained with `to_html_datatable`. See more in the section on [HTML export](html.md).

docs/downsampling.md

@@ -20,11 +20,13 @@ kernelspec:
 
 # Downsampling
 
-When an interactive table is displayed by `itables`, the table data is embedded in the notebook output. As we don't want your notebook to become super heavy just because you displayed a large table, we have a downsampling mechanism in place.
+When an interactive table is displayed by `itables`, the table data is embedded into the notebook itself. Large tables need to be downsampled, otherwise your notebook will become huge and irresponsive.
 
-When the data in a table is larger than `maxBytes`, which is equal to 64KB by default, `itables` will display only a subset of the table - one that fits into `maxBytes`, and display a warning that points to the `itables` documentation.
+Downsampling occurs when the table data is larger than `maxBytes`, which is equal to 64KB by default. When downsampling occurs, a warning is displayed below the table, which points to the `itables` documentation.
 
-If you wish, you can increase the value of `maxBytes` or even deactivate the limit (with `maxBytes=0`). Similarly, you can set a limit on the number of rows (`maxRows`, defaults to 0) or columns (`maxColumns`, defaults to `200`).
+If you wish, you can increase the value of `maxBytes` or even deactivate the limit (with `maxBytes=0`) - but again, that will break your notebook when you display a large dataframe.
+
+Similarly, you can set a limit on the number of rows (`maxRows`, defaults to 0) or columns (`maxColumns`, defaults to `200`).
 
 ```{code-cell} ipython3
 import itables
@@ -33,10 +35,11 @@ itables.init_notebook_mode()
 ```
 
 ```{code-cell} ipython3
-itables.options.lengthMenu = [2, 5, 10, 20, 50, 100, 200, 500]
+:tags: [full-width]
+
 itables.options.maxBytes = "8KB"
 
-df = itables.sample_dfs.get_indicators()
+df = itables.sample_dfs.get_countries(html=False)
 itables.downsample.as_nbytes(itables.options.maxBytes), itables.downsample.nbytes(df)
 ```
 
@@ -51,7 +54,7 @@ To show the table in full, we can modify the value of `maxBytes` either locally:
 ```{code-cell} ipython3
 :tags: [full-width]
 
-itables.show(df, maxBytes=0)
+itables.show(df, maxBytes=32768)
 ```
 
 or globally:

docs/options/buttons.md

@@ -19,6 +19,8 @@ The DataTables [buttons](https://datatables.net/extensions/buttons/) let you cop
 To display the buttons, you need to pass a `buttons` argument to the `show` function:
 
 ```{code-cell} ipython3
+:tags: [full-width]
+
 import itables
 
 itables.init_notebook_mode()

docs/py/apps/notebook.py

@@ -14,6 +14,9 @@
 #     name: itables
 # ---
 
+# %% tags=["remove-cell"]
+# pyright: reportUnusedExpression=false
+
 # %% [markdown]
 # # Notebook Mode
 #
@@ -26,7 +29,12 @@
 
 # %% [markdown]
 # You can go back to the standard HTML representation of Pandas DataFrames with `init_notebook_mode(all_interactive=False)`.
-#
+
+# %% tags=["full-width"]
+df = itables.sample_dfs.get_countries(html=False)
+df
+
+# %% [markdown]
 # Note that the `init_connected_mode` function also activates ITable's offline mode, unless you call it with a `connected=False` argument.
 #
 #
@@ -44,16 +52,5 @@
 #
 # If you prefer to render only certain tables using `itables`, or want to set additional options, use `show`:
 
-# %%
-df = itables.sample_dfs.get_countries(html=False)
-
-itables.show(
-    df,
-    caption="A DataFrame rendered with ITables",
-    lengthMenu=[2, 5, 10, 25, 50, 100, 250],
-)
-
-# %% [markdown]
-# ## HTML
-#
-# The `show` function simply displays the HTML snippet for the table, which is obtained with `to_html_datatable`. See more in the section on [HTML export](html.md).
+# %% tags=["full-width"]
+itables.show(df, caption="A DataFrame rendered with ITables")

docs/py/downsampling.py

@@ -20,22 +20,23 @@
 # %% [markdown]
 # # Downsampling
 #
-# When an interactive table is displayed by `itables`, the table data is embedded in the notebook output. As we don't want your notebook to become super heavy just because you displayed a large table, we have a downsampling mechanism in place.
+# When an interactive table is displayed by `itables`, the table data is embedded into the notebook itself. Large tables need to be downsampled, otherwise your notebook will become huge and irresponsive.
 #
-# When the data in a table is larger than `maxBytes`, which is equal to 64KB by default, `itables` will display only a subset of the table - one that fits into `maxBytes`, and display a warning that points to the `itables` documentation.
+# Downsampling occurs when the table data is larger than `maxBytes`, which is equal to 64KB by default. When downsampling occurs, a warning is displayed below the table, which points to the `itables` documentation.
 #
-# If you wish, you can increase the value of `maxBytes` or even deactivate the limit (with `maxBytes=0`). Similarly, you can set a limit on the number of rows (`maxRows`, defaults to 0) or columns (`maxColumns`, defaults to `200`).
+# If you wish, you can increase the value of `maxBytes` or even deactivate the limit (with `maxBytes=0`) - but again, that will break your notebook when you display a large dataframe.
+#
+# Similarly, you can set a limit on the number of rows (`maxRows`, defaults to 0) or columns (`maxColumns`, defaults to `200`).
 
 # %%
 import itables
 
 itables.init_notebook_mode()
 
-# %%
-itables.options.lengthMenu = [2, 5, 10, 20, 50, 100, 200, 500]
+# %% tags=["full-width"]
 itables.options.maxBytes = "8KB"
 
-df = itables.sample_dfs.get_indicators()
+df = itables.sample_dfs.get_countries(html=False)
 itables.downsample.as_nbytes(itables.options.maxBytes), itables.downsample.nbytes(df)
 
 # %% tags=["full-width"]
@@ -45,7 +46,7 @@
 # To show the table in full, we can modify the value of `maxBytes` either locally:
 
 # %% tags=["full-width"]
-itables.show(df, maxBytes=0)
+itables.show(df, maxBytes=32768)
 
 # %% [markdown]
 # or globally:

docs/py/options/buttons.py

@@ -21,7 +21,7 @@
 #
 # To display the buttons, you need to pass a `buttons` argument to the `show` function:
 
-# %%
+# %% tags=["full-width"]
 import itables
 
 itables.init_notebook_mode()

docs/py/quick_start.py

@@ -61,7 +61,7 @@
 #
 # ## Activate ITables
 #
-# Activate the interactive mode in notebook-like environment with `init_notebook_mode`:
+# Activate the interactive mode in notebook-like environment with [`init_notebook_mode`](apps/notebook.md):
 
 # %%
 import itables
@@ -73,7 +73,7 @@
 # is displayed as an interactive [DataTables](https://datatables.net/),
 # which lets you explore, filter or sort your data.
 
-# %%
+# %% tags=["full-width"]
 df = itables.sample_dfs.get_countries(html=False)
 df
 

docs/quick_start.md

@@ -61,7 +61,7 @@ conda install itables -c conda-forge
 
 ## Activate ITables
 
-Activate the interactive mode in notebook-like environment with `init_notebook_mode`:
+Activate the interactive mode in notebook-like environment with [`init_notebook_mode`](apps/notebook.md):
 
 ```{code-cell} ipython3
 import itables
@@ -74,6 +74,8 @@ is displayed as an interactive [DataTables](https://datatables.net/),
 which lets you explore, filter or sort your data.
 
 ```{code-cell} ipython3
+:tags: [full-width]
+
 df = itables.sample_dfs.get_countries(html=False)
 df
 ```