Use simpler examples

Author: mwouts

docs/options/options.md

@@ -20,7 +20,11 @@ ITables is a wrapper for the Javascript DataTables library, which means that you
 
 Since ITables just maps these options to DataTables, you are invited to have a look at DataTable's great [documentation](https://datatables.net/), and to its huge collection of [examples](https://datatables.net/examples/index). The DataTable [forum](https://datatables.net/forums/) can be quite useful as well.
 
-A non-exhaustive list of the DataTable options, together with their expected types, is available at [`itables.typing.DataTableOptions`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py). If you see an option that you find useful, please make a PR (and add an example to the documentation, too).
+A non-exhaustive list of the DataTable options, together with their expected types, is available at [`itables.typing.DataTableOptions`](https://github.com/mwouts/itables/blob/main/src/itables/typing.py).
+
+Option names and types are checked by default at run time when `typeguard>=4.4.1` is installed - you can deactivate this by setting `warn_on_undocumented_option=False`.
+
+If you see an option that you find useful and is not documented, or a type hint that is incorrect, please make a PR (and add an example to the documentation, too).
 
 ```{code-cell} ipython3
 :tags: [scroll-output]

docs/options/order.md

@@ -14,7 +14,9 @@ kernelspec:
 
 # Order
 
-Since `itables>=1.3.0`, the interactive datatable shows the rows in the same order as the original dataframe:
+Since ITables v1.3.0, the interactive datatable shows the rows in the same order as the original dataframe.
+
+You can pre-select a explicit order with the [`order`](https://datatables.net/reference/option/order) option:
 
 ```{code-cell} ipython3
 import pandas as pd
@@ -23,14 +25,6 @@ import itables
 
 itables.init_notebook_mode()
 
-for name, test_df in itables.sample_dfs.get_dict_of_test_dfs().items():
-    if "sorted" in name:
-        itables.show(test_df, caption=name.replace("_", " ").title())
-```
-
-You can also set an explicit [`order`](https://datatables.net/reference/option/order) argument:
-
-```{code-cell} ipython3
 sorted_df = pd.DataFrame({"i": [1, 2], "a": [2, 1]}).set_index(["i"])
 itables.show(sorted_df, order=[[1, "asc"]])
 ```

docs/options/scroll_x.md

@@ -14,7 +14,11 @@ kernelspec:
 
 # Horizontal Scroll
 
-Since ITables 2.1.2, the `.dt-layout-table` div has a default overflow equal to `auto`, so in most cases you don't need to use the [`scrollX`](https://datatables.net/reference/option/scrollX) option of datatables.
+DataTables has a [`scrollX`](https://datatables.net/reference/option/scrollX) option that might be helpful for wide tables.
+
+```{tip}
+Since ITables v2.1.2, the `.dt-layout-table` div has a default overflow equal to `auto`, so in most cases you don't need to use `scrollX`.
+```
 
 ```{code-cell} ipython3
 :tags: [full-width]
@@ -23,6 +27,10 @@ import itables
 
 itables.init_notebook_mode()
 
-df = itables.sample_dfs.get_countries(html=False)
+df = itables.sample_dfs.get_dict_of_test_dfs()["wide"]
 itables.show(df, scrollX=True)
 ```
+
+```{warning}
+Using `scrollX` on a table that is not wide enough can lead to an issue where the table headers are not aligned with the table content.
+```

docs/options/scroll_y.md

@@ -14,7 +14,7 @@ kernelspec:
 
 # Vertical Scroll
 
-You can replace the pagination with a [vertical scroll](https://datatables.net/examples/basic_init/scroll_y.html):
+The [`scrollY`](https://datatables.net/examples/basic_init/scroll_y.html) parameter is an interesting alternative to the pagination:
 
 ```{code-cell} ipython3
 :tags: [full-width]
@@ -24,5 +24,5 @@ import itables
 itables.init_notebook_mode()
 
 df = itables.sample_dfs.get_countries(html=False)
-itables.show(df, scrollY="200px", scrollCollapse=True, paging=False)
+itables.show(df, scrollY="350px", scrollCollapse=True, paging=False)
 ```