Finished tables documentation

docs/examples/references.py

@@ -14,7 +14,7 @@
 N = 10
 np.random.seed(1)
 df = pd.DataFrame({"x": np.arange(1, N + 1), "y": np.random.random(N) * 4 + 3})
-pb.print_table(df, caption="A data table.")
+pb.print_table(df, caption="A data table.", index=False)
 
 img_reference = pb.Reference()
 table_ref = pb.Reference()
@@ -28,11 +28,18 @@
     f"For example, here is a link to {img_reference('Scatterplot')}."
 )
 pb.print_table(
-    df, caption="A sortable table with a reference", reference=table_ref, sortable=True
+    df,
+    caption="A sortable table with a reference",
+    reference=table_ref,
+    sortable=True,
+    index=False,
 )
 
 pb.print_table(
-    df, caption="A table sorted by y column", sorting_definition=("y", "asc")
+    df,
+    caption="A table sorted by y column",
+    sorting_definition=[(df.columns.get_loc("y"), "asc")],
+    index=False,
 )
 
 pb.print_h1("Charts")

docs/examples/table_captions.py

@@ -10,7 +10,4 @@
 pb.print_table(df, caption="People with their age.")
 pb.print_table(df, caption="People with their age.", numbered=False)
 pb.print_table(df, numbered=False)
-pb.print_table(
-    df,
-    caption="The table with numbering again. But much bigger caption.",
-)
+pb.print_table(df, caption="The table with numbering again.")

docs/examples/table_datatables_definition.py

@@ -0,0 +1,19 @@
+import pandas as pd
+import pyreball as pb
+
+df = pd.DataFrame(
+    [[row * 20 + col for col in range(20)] for row in range(40)],
+    columns=[f"col_{i}" for i in range(20)],
+)
+datatables_definition = {
+    "paging": False,
+    "scrollCollapse": True,
+    "scrollY": "400px",
+    "searching": False,
+    "order": [(1, "desc")],
+}
+pb.print_table(
+    df,
+    caption="Larger table with custom config.",
+    datatables_definition=datatables_definition,
+)

docs/examples/table_paging.py

@@ -0,0 +1,13 @@
+import pandas as pd
+import pyreball as pb
+
+df = pd.DataFrame(
+    [[row * 20 + col for col in range(20)] for row in range(40)],
+    columns=[f"col_{i}" for i in range(20)],
+)
+pb.print_table(
+    df,
+    caption="Larger table with paging.",
+    display_option="paging",
+    paging_sizes=[5, 10, "All"],
+)

docs/examples/table_scrolling.py

@@ -0,0 +1,13 @@
+import pandas as pd
+import pyreball as pb
+
+df = pd.DataFrame(
+    [[row * 20 + col for col in range(20)] for row in range(40)],
+    columns=[f"col_{i}" for i in range(20)],
+)
+pb.print_table(
+    df,
+    caption="Larger table with scrolling.",
+    display_option="scrolling",
+    scroll_y_height="500px",
+)

docs/examples/table_searching.py

@@ -0,0 +1,14 @@
+import pandas as pd
+import pyreball as pb
+
+df = pd.DataFrame(
+    {
+        "name": ["Bob", "Carol", "Alice", "Dave"],
+        "age": [23, 5, 22, 54],
+    }
+)
+pb.print_table(
+    df,
+    caption="Table with a search box.",
+    show_search_box=True,
+)

docs/examples/table_sorting.py

@@ -18,3 +18,9 @@
     caption="Table sorted by name (ASC) and age (DESC).",
     sorting_definition=[(1, "asc"), (2, "desc")],
 )
+pb.print_table(
+    df,
+    caption="The same table, but without the index.",
+    index=False,
+    sorting_definition=[(0, "asc"), (1, "desc")],
+)

docs/examples/table_styling.py

@@ -0,0 +1,19 @@
+import pandas as pd
+import pyreball as pb
+
+df = pd.DataFrame(
+    {
+        "name": ["Bob", "Carol", "Alice", "Dave"],
+        "age": [23, 5, 22, 54],
+    }
+)
+pb.print_table(
+    df,
+    caption="Style set to 'compact'.",
+    datatables_style="compact",
+)
+pb.print_table(
+    df,
+    caption="Style set to 'compact' and 'display'.",
+    datatables_style=["compact", "display"],
+)

docs/tables.md

@@ -1,11 +1,12 @@
 # Tables
 
 Pyreball allows printing [pandas DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) objects
-into HTML tables by using [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) function.
+into HTML tables with [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) function.
+Moreover, Pyreball uses [DataTables](https://datatables.net/) library to add styling and interactivity to the tables.
 
 ## Basic Usage
 
-The simplest usage is to provide just the `DataFrame` object:
+The simplest usage is to provide just a `DataFrame` object:
 
 {{ inline_source("docs/examples/table_simplest.py") }}
 
@@ -14,18 +15,21 @@ The simplest usage is to provide just the `DataFrame` object:
 ## Captions
 
 All tables are numbered by default, which causes creation of `Table 1.` table caption above.
-It is possible to provide custom caption via `caption` parameter, as well as to control the numbering of form `Table k.`
-via `numbered` parameter.
+It is possible to provide custom caption text via `caption` parameter.
+To control whether `Table k.` prefix should be displayed, one can use `numbered` Boolean parameter.
 
 {{ inline_source("docs/examples/table_captions.py") }}
 
 <iframe style="border:2px solid;" src="../examples/table_captions.html" height="1000" width="100%" title="Iframe Example"></iframe>
 
-Note that internally all tables are numbered, even though the numbering might be turned off.
+!!! note
+
+    All tables are internally numbered, even though the numbering might be turned off for specific tables, as shown
+    in the previous example.
 
 ## Caption Position
 
-By default, the caption is positioned at the top of the table.
+By default, the caption is positioned above the table.
 The position can be controlled by `caption_position`  parameter, which can be set either to `top` or `bottom`.,
 
 {{ inline_source("docs/examples/table_caption_position.py") }}
@@ -54,21 +58,69 @@ The following snippet shows the usage of both parameters.
 !!! note
 
     Although the columns in `sorting_definition` are indexed from 0, it is necessary to take into account
-    also the index when it is displayed. To hide the index, set `index` parameter 
+    also the table index when it is displayed. To hide the index, set `index` parameter 
     of [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) method to `False`. 
-    `index` parameter is one of the `kwargs` that are passed to pandas `to_html()` method.
+    `index` parameter is one of the `kwargs` parameters that are passed to pandas `to_html()` method.
 
 {{ inline_source("docs/examples/table_sorting.py") }}
 
-<iframe style="border:2px solid;" src="../examples/table_sorting.html" height="900" width="100%" title="Iframe Example"></iframe>
+<iframe style="border:2px solid;" src="../examples/table_sorting.html" height="1200" width="100%" title="Iframe Example"></iframe>
 
 ## Dealing with Large Tables
 
-TBD
+Each table is fully displayed by default. This is caused by `display_option` parameter's default value `full`.
+However, this might not be practical for large tables.
+
+One solution is to allow vertical scrolling of the table by setting `display_option` to `scrolling`.
+To change the default height of the table, set also `scroll_y_height` parameter.
+
+{{ inline_source("docs/examples/table_scrolling.py") }}
+
+<iframe style="border:2px solid;" src="../examples/table_scrolling.html" height="800" width="100%" title="Iframe Example"></iframe>
+
+!!! note
+
+    By default, Pyreball turns on horizontall scrolling on each table  as can be seen in the previous example.
+    You can turn it off by setting, `scroll_x` parameter to `False`, which might cause the table to overflow
+    the container.
+
+Another option is to set `display_option` to `paging`. This option can be further customized by providing custom page
+sizes through `paging_sizes` parameter. Currently, `paging_sizes` takes a list of integers mixed with string `All` (the
+case of the letters does nto matter, so it can be `all` or `ALL` as well). When `All` is used, Pyreball interprets it as
+showing all entries on a single page.
+
+{{ inline_source("docs/examples/table_paging.py") }}
+
+<iframe style="border:2px solid;" src="../examples/table_paging.html" height="800" width="100%" title="Iframe Example"></iframe>
+
+## Searching
+
+To allow searching within a table, just set `show_search_box` to `True`.
+
+{{ inline_source("docs/examples/table_searching.py") }}
+
+<iframe style="border:2px solid;" src="../examples/table_searching.html" height="360" width="100%" title="Iframe Example"></iframe>
 
 ## Styling
 
-TBD
+Tables are also styled with the help of [DataTables](https://datatables.net/) library.
+The default styling class used is `display`.
+To change the styling, use parameter `datatables_style`, which takes either a single string with a class name,
+or a list of class names.
+Usable class names are listed in the styling reference
+of [Datatables documentation](https://datatables.net/manual/styling/classes).
+
+{{ inline_source("docs/examples/table_styling.py") }}
+
+<iframe style="border:2px solid;" src="../examples/table_styling.html" height="500" width="100%" title="Iframe Example"></iframe>
+
+## Custom DataTables Configuration
+
+Most of the parameters in the previous sections were just setting up the parameters of `DataTable` JavaScript object
+in some predefined manner.
+It is possible to completely override such parameters by providing custom dictionary via `datatables_definition`
+parameter. This dictionary is then serialized into JSON and passed to the `DataTable` JavaScript object.
+
+{{ inline_source("docs/examples/table_datatables_definition.py") }}
 
-For more options, see the styling reference
-in [Datatables documentation](https://datatables.net/manual/styling/classes). 
+<iframe style="border:2px solid;" src="../examples/table_datatables_definition.html" height="660" width="100%" title="Iframe Example"></iframe>