Skip to content

Commit

Permalink
Redesigning tables
Browse files Browse the repository at this point in the history
  • Loading branch information
@karelvaculik
karelvaculik committed Sep 6, 2023
1 parent 3bace23 commit 59a450f
Show file tree
Hide file tree
Showing 10 changed files with 846 additions and 350 deletions.
41 changes: 24 additions & 17 deletions docs/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,25 +105,32 @@ parameters. The following table shows the parameter alternatives between these t

!!! note

When the table mentions allowed values `yes` and `no`, the allowed values of functions parameters are actually
Acceptable values mentioned in the table below are primarily intended for `config.ini` and CLI arguments.
The function arguments might be slightly different, so it's recommended to see appropriate API documentation
of given function. For example, instead of values `yes` and `no`, the functions usually use Boolean values
`True` and `False`.

| `config.ini` key | CLI argument | Function argument | Description |
|---------------------------|-----------------------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| `toc` | `--toc ` | _N/A_ | Include table of contents. It is included only when there are any headings. Allowed values: `yes`, `no`. |
| `align-tables` | `--align-tables` | `align` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Horizontal alignment of tables. Allowed values: `left`, `center`, `right`. |
| `table-captions-position` | `--table-captions-position` | `caption_position` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Caption position. Allowed values: `top`, `bottom`. |
| `numbered-tables` | `--numbered-tables` | `numbered` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to number tables. Allowed values: `yes`, `no`. |
| `sortable-tables` | `--sortable-tables` | `sortable` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to make columns in tables sortable. Allowed values: `yes`, `no`. |
| `full-tables` | `--full-tables` | `full_table` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to show tables expanded. Allowed values: `yes`, `no`. |
| `align-plots` | `--align-plots` | `align` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Horizontal alignment of plots. Allowed values: `left`, `center`, `right`. |
| `plot-captions-position` | `--plot-captions-position` | `caption_position` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Caption position. Allowed values: `top`, `bottom`. |
| `numbered-plots` | `--numbered-plots` | `numbered` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to number plots. Allowed values: `yes`, `no`. |
| `matplotlib-format` | `--matplotlib-format` | `matplotlib_format` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Format of matplotlib (and thus also seaborn) plots. Allowed values: `png`, `svg`. |
| `matplotlib-embedded` | `--matplotlib-embedded` | `embedded` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to embedded matplotlib (and thus also seaborn) plots directly into HTML. Only for svg format. Allowed values: `yes`, `no`. |
| `numbered-headings` | `--numbered-headings` | _N/A_ | Whether to number headings. Allowed values: `yes`, `no`. |
| `page-width` | `--page-width` | _N/A_ | Width of the page container in percentage. Allowed values: An integer in the range 40..100. |
| `keep-stdout` | `--keep-stdout` | _N/A_ | Whether to print the output to stdout too: `yes`, `no`. |
| `config.ini` key | CLI argument | Function argument | Description |
|---------------------------|-----------------------------|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `toc` | `--toc ` | _N/A_ | Include table of contents. It is included only when there are any headings. Allowed values: `yes`, `no`. |
| `align-tables` | `--align-tables` | `align` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Horizontal alignment of tables. Allowed values: `left`, `center`, `right`. |
| `table-captions-position` | `--table-captions-position` | `caption_position` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Caption position. Allowed values: `top`, `bottom`. |
| `numbered-tables` | `--numbered-tables` | `numbered` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to number tables. Allowed values: `yes`, `no`. |
| `tables-display-option` | `--tables-display-option` | `display_option` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | How to display table. This option is useful for long tables, which should not be displayed fully. Allowed values are: `full` (show the full table), `scrolling` (show the table in scrolling mode on y-axis), `paging` (show the table in paging mode). |
| `tables-paging-sizes` | `--tables-paging-sizes` | `paging_sizes` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | The paging sizes that can be selected. Ignored when `tables-display-option` is not `paging`. Allowed values are integers and string `all` (no matter the case of letters), written as a non-empty comma-separated list. |
| `tables-scroll-y-height` | `--tables-scroll-y-height` | `scroll_y_height` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Height of the tables when `tables-display-option` is set to `scrolling`. Allowed values TODO |
| `tables-scroll-x` | `--tables-scroll-x` | `scroll_x` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to allow scrolling on the x-axis. If turned off, a wide table is allowed to overflow the main container. It is recommended to turn this on, especially with `tables-display-option` set to `scrolling`, because otherwise the table header won't interact properly when scrolling horizontally. Allowed values: `yes`, `no`. |
| `sortable-tables` | `--sortable-tables` | `sortable` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to make columns in tables sortable. Allowed values: `yes`, `no`. |
| `tables-search-box` | `--tables-search-box` | `show_search_box` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Whether to show the search box for the tables. Allowed values: `yes`, `no`. |
| `tables-datatables-style` | `--tables-datatables-style` | `datatables_style` in [`print_table()`](../api/pyreball_html/#pyreball.html.print_table) | Datatables class(es) that affect the tables styling. If multiple classes are provided, separate them either with commas or spaces. See [DataTables documentation](https://datatables.net/manual/styling/classes) with the possible values. |
| `align-plots` | `--align-plots` | `align` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Horizontal alignment of plots. Allowed values: `left`, `center`, `right`. |
| `plot-captions-position` | `--plot-captions-position` | `caption_position` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Caption position. Allowed values: `top`, `bottom`. |
| `numbered-plots` | `--numbered-plots` | `numbered` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to number plots. Allowed values: `yes`, `no`. |
| `matplotlib-format` | `--matplotlib-format` | `matplotlib_format` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Format of matplotlib (and thus also seaborn) plots. Allowed values: `png`, `svg`. |
| `matplotlib-embedded` | `--matplotlib-embedded` | `embedded` in [`plot_graph()`](../api/pyreball_html/#pyreball.html.plot_graph) | Whether to embedded matplotlib (and thus also seaborn) plots directly into HTML. Only for svg format. Allowed values: `yes`, `no`. |
| `numbered-headings` | `--numbered-headings` | _N/A_ | Whether to number headings. Allowed values: `yes`, `no`. |
| `page-width` | `--page-width` | _N/A_ | Width of the page container in percentage. Allowed values: An integer in the range 40..100. |
| `keep-stdout` | `--keep-stdout` | _N/A_ | Whether to print the output to stdout too: `yes`, `no`. |

The reason for having multiple options for setting these values is to allow the user to set some properties globally,
while others locally as needed for particular scripts.
Expand Down
9 changes: 9 additions & 0 deletions docs/tables.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ Tables can be horizontally aligned by `align` parameter, as shown in the followi

## Sorting

TODO: update this section.

It is possible to make the table sortable on all columns by setting `sortable` parameter to `True`,
or by setting `sorting_definition` parameter, which also sorts the table initially on the specified column.

Expand All @@ -52,3 +54,10 @@ or by setting `sorting_definition` parameter, which also sorts the table initial
## Dealing with Large Tables

TBD

## Styling

TBD

For more options, see the styling reference
in [Datatables documentation](https://datatables.net/manual/styling/classes).
76 changes: 54 additions & 22 deletions pyreball/__main__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,12 @@
from pyreball.utils.utils import (
carefully_remove_directory_if_exists,
check_and_fix_parameters,
check_paging_sizes_string_parameter,
ChoiceParameter,
get_file_config,
IntegerParameter,
merge_parameter_dictionaries,
StringParameter,
Substitutor,
)

Expand Down Expand Up @@ -100,18 +102,6 @@
"""

JAVASCRIPT_SORTABLE_TABLE = """
$(document).ready(function () {
$('.sortable_table').DataTable({
"paging": false,
"searching": false,
"info": false,
});
});
"""


def _replace_ids(html_path: Path) -> None:
"""
Expand Down Expand Up @@ -313,17 +303,56 @@ def insert_heading_title_and_toc(filename: Path, include_toc: bool = True):
default="no",
help="Number the tables.",
),
ChoiceParameter(
"--tables-display-option",
choices=["full", "paging", "scrolling"],
default="full",
help="How to display tables. Either full, with scrollbar, or with paging.",
),
StringParameter(
"--tables-paging-sizes",
default="10,25,100,All",
help=(
"The paging sizes that can be selected. "
"Allowed values are integers and string 'all' (no matter the case of letters), "
"written as a non-empty comma-separated list. "
"Ignored when tables-display-option is not 'paging'."
),
validation_function=check_paging_sizes_string_parameter,
),
# TODO add more details what values can be passed here:
StringParameter(
"--tables-scroll-y-height",
default="300px",
help=(
"Height of the tables when 'scrolling' display option is set. Ignored with other display options."
),
),
ChoiceParameter(
"--tables-scroll-x",
choices=["yes", "no"],
default="yes",
help="Whether to allow horizontal scrolling on tables.",
),
ChoiceParameter(
"--sortable-tables",
choices=["yes", "no"],
default="no",
help="Make the tables sortable.",
help="Whether to make the tables sortable.",
),
ChoiceParameter(
"--full-tables",
"--tables-search-box",
choices=["yes", "no"],
default="no",
help="Force all tables to be expanded.",
help="Whether to show search box for tables.",
),
StringParameter(
"--tables-datatables-style",
default="display",
help=(
"Datatables class(es) that affect the tables styling. If multiple classes are provided, "
"separate them either with commas or spaces."
),
),
ChoiceParameter(
"--align-plots",
Expand Down Expand Up @@ -537,13 +566,19 @@ def parse_arguments(args) -> Dict[str, Optional[Union[str, int]]]:
nargs=argparse.REMAINDER,
help="Remaining arguments that are passed to the Python script.",
)
return vars(parser.parse_args(args))
variables = vars(parser.parse_args(args))
# positional arguments must be renamed manually
variables['input_path'] = variables['input-path']
variables['script_args'] = variables['script-args']
del variables['input-path']
del variables['script-args']
return variables


def main() -> None:
args_dict = parse_arguments(sys.argv[1:])
script_args_string = " ".join(cast(List[str], args_dict.pop("script-args")))
input_path = cast(Path, args_dict.pop("input-path"))
script_args_string = " ".join(cast(List[str], args_dict.pop("script_args")))
input_path = cast(Path, args_dict.pop("input_path"))
input_path = input_path.expanduser().resolve()
output_path = cast(Optional[Path], args_dict.pop("output_path"))
config_path = cast(Optional[Path], args_dict.pop("config_path"))
Expand Down Expand Up @@ -584,10 +619,7 @@ def main() -> None:
carefully_remove_directory_if_exists(directory=Path(html_dir_path_str))

script_definitions = (
JAVASCRIPT_CHANGE_EXPAND
+ JAVASCRIPT_ON_LOAD
+ JAVASCRIPT_SORTABLE_TABLE
+ JAVASCRIPT_ROLLING_PLOTS
JAVASCRIPT_CHANGE_EXPAND + JAVASCRIPT_ON_LOAD + JAVASCRIPT_ROLLING_PLOTS
)

css_definitions = get_css(
Expand Down
Loading

0 comments on commit 59a450f

Please sign in to comment.