From 03d4fe4f9d6d3548b3c719f832c7a71cb18011c8 Mon Sep 17 00:00:00 2001 From: Marc Wouts Date: Sun, 28 Sep 2025 22:35:24 +0100 Subject: [PATCH] New section on the `itables.toml` configuration file --- docs/_toc.yml | 3 ++ docs/configuration.md | 64 ++++++++++++++++++++++++++++++ docs/options/buttons.md | 2 +- docs/options/classes.md | 4 +- docs/options/column_control.md | 2 +- docs/options/options.md | 36 +---------------- docs/py/configuration.py | 66 +++++++++++++++++++++++++++++++ docs/py/options/buttons.py | 2 +- docs/py/options/classes.py | 4 +- docs/py/options/column_control.py | 2 +- docs/py/options/options.py | 36 +---------------- 11 files changed, 143 insertions(+), 78 deletions(-) create mode 100644 docs/configuration.md create mode 100644 docs/py/configuration.py diff --git a/docs/_toc.yml b/docs/_toc.yml index 3a673c1b..28f353a6 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -11,6 +11,9 @@ parts: - file: apps/streamlit - file: apps/shiny - file: apps/quarto + - caption: Configuration + chapters: + - file: configuration - caption: Options chapters: - file: options/options diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..f111d1ea --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,64 @@ +--- +jupytext: + formats: docs///md:myst,docs/py///py:percent + 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 +--- + +# Configuration + +ITables exposes many of the `datatables` [options](options/options.md). Since ITables v2.5, the default values for these options can be set in an `itables.toml` configuration file. + +## Prerequisites + +You will need ITables v2.5 or higher, and two dependencies: either `tomllib` or `tomli`, and `platformdirs`, which can be installed with `pip install itables[config]`. + +## Configuration file + +The configuration file is identified using `get_config_file` from [`itables.config`](https://github.com/mwouts/itables/blob/main/src/itables/config.py). It can be: + +- The file pointed to by the environment variable `ITABLES_CONFIG`, if set and non-empty (if the variable is an empty string, no configuration file is used) +- An `itables.toml` file in the current directory or a parent directory +- A `tool.itables` section in a `pyproject.toml` file in the current directory or a parent directory + +## Example configuration + +A simple `itables.toml` configuration file that makes the tables a bit more [compact](options/classes.md) looks like this: +``` +classes = ["display", "nowrap", "compact"] +``` + +If you want the Excel export button on each table, add this: +``` +buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"] +``` + +And if you want to use the [column control](options/column_control.md) extension: +``` +[[columnControl]] +target = 0 +content = ["order"] +[[columnControl]] +target = "tfoot" +content = ["search"] + +[ordering] +indicators = false +handler = false +``` + +## Modifying the configuration + +The configuration file is loaded when `itables` is imported. If you make changes to the configuration file, these will take effect only when you restart Python and re-import ITables. + +You can confirm which configuration file is being used (in a given directory) by running: +``` +python -m itables.show_config +``` diff --git a/docs/options/buttons.md b/docs/options/buttons.md index f9bbebfc..57ed256b 100644 --- a/docs/options/buttons.md +++ b/docs/options/buttons.md @@ -43,7 +43,7 @@ You can also add ``` buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"] ``` -to your `itables.toml` configuration file. +to your `itables.toml` [configuration file](../configuration.md). By default, the exported file name is the name of the HTML page. To change it, set a diff --git a/docs/options/classes.md b/docs/options/classes.md index fe262230..51b60af8 100644 --- a/docs/options/classes.md +++ b/docs/options/classes.md @@ -46,8 +46,8 @@ itables.show(df, classes="display") itables.show(df, classes="display nowrap cell-border") ``` -```tip -You can change the default for all your notebooks and apps by creating an `itables.toml` file in the current or a parent directory, with e.g. this content: +```{tip} +You can change the default for all your notebooks and apps by creating an `itables.toml` [configuration file](../configuration.md) in the current or a parent directory, with e.g. this content: ~~~ classes = ["display", "nowrap", "compact"] ~~~ diff --git a/docs/options/column_control.md b/docs/options/column_control.md index a77b298b..cc609e83 100644 --- a/docs/options/column_control.md +++ b/docs/options/column_control.md @@ -73,7 +73,7 @@ itables.show( ) ``` -As usual, you can make this the default by either setting `itables.options.columnControl` in your notebook or application, or by adding this to your `itables.toml` configuration file: +As usual, you can make this the default by either setting `itables.options.columnControl` in your notebook or application, or by adding this to your `itables.toml` [configuration file](../configuration.md): ``` [[columnControl]] target = 0 diff --git a/docs/options/options.md b/docs/options/options.md index 1c4af568..acb7b30e 100644 --- a/docs/options/options.md +++ b/docs/options/options.md @@ -42,41 +42,7 @@ itables.options.maxBytes = "128KB" ## Configuration File -Since v2.5.0, ITable can load its default options from a configuration file. This requires two dependencies: either `tomllib` or `tomli`, and `platformdirs`, which can be installed with `pip install itables[config]`. - -The configuration file is identified using `get_config_file` from [`itables.config`](https://github.com/mwouts/itables/blob/main/src/itables/config.py). It can be: - -- The file pointed to by the environment variable `ITABLES_CONFIG`, if set and non-empty (if the variable is an empty string, no configuration file is used) -- An `itables.toml` file in the current or a parent directory -- A `tool.itables` section in a `pyproject.toml` file in the current or a parent directory - -A sample configuration file could look like this: -``` -# itables.toml -classes = ["display", "nowrap", "compact"] -buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"] -``` - -Add this to use the [column control](column_control.md) extension: -``` -[[columnControl]] -target = 0 -content = ["order"] -[[columnControl]] -target = "tfoot" -content = ["search"] - -[ordering] -indicators = false -handler = false -``` - -The configuration file is loaded when `itables` is imported - you will need to restart Python and re-import ITables to get the latest configuration. - -You can confirm which configuration file is being used (in a given directory) by running -``` -python -m itables.show_config -``` +You can also change the default options for all your notebooks and applications by creating an `itables.toml` [configuration file](../configuration.md). ## Option Names and Type Checks diff --git a/docs/py/configuration.py b/docs/py/configuration.py new file mode 100644 index 00000000..8d826192 --- /dev/null +++ b/docs/py/configuration.py @@ -0,0 +1,66 @@ +# --- +# jupyter: +# jupytext: +# formats: docs///md:myst,docs/py///py:percent +# notebook_metadata_filter: -jupytext.text_representation.jupytext_version +# text_representation: +# extension: .py +# format_name: percent +# format_version: '1.3' +# kernelspec: +# display_name: itables +# language: python +# name: itables +# --- + +# %% [markdown] +# # Configuration +# +# ITables exposes many of the `datatables` [options](options/options.md). Since ITables v2.5, the default values for these options can be set in an `itables.toml` configuration file. +# +# ## Prerequisites +# +# You will need ITables v2.5 or higher, and two dependencies: either `tomllib` or `tomli`, and `platformdirs`, which can be installed with `pip install itables[config]`. +# +# ## Configuration file +# +# The configuration file is identified using `get_config_file` from [`itables.config`](https://github.com/mwouts/itables/blob/main/src/itables/config.py). It can be: +# +# - The file pointed to by the environment variable `ITABLES_CONFIG`, if set and non-empty (if the variable is an empty string, no configuration file is used) +# - An `itables.toml` file in the current directory or a parent directory +# - A `tool.itables` section in a `pyproject.toml` file in the current directory or a parent directory +# +# ## Example configuration +# +# A simple `itables.toml` configuration file that makes the tables a bit more [compact](options/classes.md) looks like this: +# ``` +# classes = ["display", "nowrap", "compact"] +# ``` +# +# If you want the Excel export button on each table, add this: +# ``` +# buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"] +# ``` +# +# And if you want to use the [column control](options/column_control.md) extension: +# ``` +# [[columnControl]] +# target = 0 +# content = ["order"] +# [[columnControl]] +# target = "tfoot" +# content = ["search"] +# +# [ordering] +# indicators = false +# handler = false +# ``` +# +# ## Modifying the configuration +# +# The configuration file is loaded when `itables` is imported. If you make changes to the configuration file, these will take effect only when you restart Python and re-import ITables. +# +# You can confirm which configuration file is being used (in a given directory) by running: +# ``` +# python -m itables.show_config +# ``` diff --git a/docs/py/options/buttons.py b/docs/py/options/buttons.py index 3e1fd31f..8ff4ef36 100644 --- a/docs/py/options/buttons.py +++ b/docs/py/options/buttons.py @@ -44,7 +44,7 @@ # ``` # buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"] # ``` -# to your `itables.toml` configuration file. +# to your `itables.toml` [configuration file](../configuration.md). # # # By default, the exported file name is the name of the HTML page. To change it, set a diff --git a/docs/py/options/classes.py b/docs/py/options/classes.py index 5119d970..88b35062 100644 --- a/docs/py/options/classes.py +++ b/docs/py/options/classes.py @@ -43,8 +43,8 @@ itables.show(df, classes="display nowrap cell-border") # %% [markdown] -# ```tip -# You can change the default for all your notebooks and apps by creating an `itables.toml` file in the current or a parent directory, with e.g. this content: +# ```{tip} +# You can change the default for all your notebooks and apps by creating an `itables.toml` [configuration file](../configuration.md) in the current or a parent directory, with e.g. this content: # ~~~ # classes = ["display", "nowrap", "compact"] # ~~~ diff --git a/docs/py/options/column_control.py b/docs/py/options/column_control.py index a06ef576..3d6e1d16 100644 --- a/docs/py/options/column_control.py +++ b/docs/py/options/column_control.py @@ -74,7 +74,7 @@ ) # %% [markdown] -# As usual, you can make this the default by either setting `itables.options.columnControl` in your notebook or application, or by adding this to your `itables.toml` configuration file: +# As usual, you can make this the default by either setting `itables.options.columnControl` in your notebook or application, or by adding this to your `itables.toml` [configuration file](../configuration.md): # ``` # [[columnControl]] # target = 0 diff --git a/docs/py/options/options.py b/docs/py/options/options.py index f73e1506..1e2948f1 100644 --- a/docs/py/options/options.py +++ b/docs/py/options/options.py @@ -44,41 +44,7 @@ # # ## Configuration File # -# Since v2.5.0, ITable can load its default options from a configuration file. This requires two dependencies: either `tomllib` or `tomli`, and `platformdirs`, which can be installed with `pip install itables[config]`. -# -# The configuration file is identified using `get_config_file` from [`itables.config`](https://github.com/mwouts/itables/blob/main/src/itables/config.py). It can be: -# -# - The file pointed to by the environment variable `ITABLES_CONFIG`, if set and non-empty (if the variable is an empty string, no configuration file is used) -# - An `itables.toml` file in the current or a parent directory -# - A `tool.itables` section in a `pyproject.toml` file in the current or a parent directory -# -# A sample configuration file could look like this: -# ``` -# # itables.toml -# classes = ["display", "nowrap", "compact"] -# buttons = ["pageLength", "copyHtml5", "csvHtml5", "excelHtml5"] -# ``` -# -# Add this to use the [column control](column_control.md) extension: -# ``` -# [[columnControl]] -# target = 0 -# content = ["order"] -# [[columnControl]] -# target = "tfoot" -# content = ["search"] -# -# [ordering] -# indicators = false -# handler = false -# ``` -# -# The configuration file is loaded when `itables` is imported - you will need to restart Python and re-import ITables to get the latest configuration. -# -# You can confirm which configuration file is being used (in a given directory) by running -# ``` -# python -m itables.show_config -# ``` +# You can also change the default options for all your notebooks and applications by creating an `itables.toml` [configuration file](../configuration.md). # # # ## Option Names and Type Checks