New section on the itables.toml configuration file

Author: mwouts

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

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
+```

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

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"]
 ~~~

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

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

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
+# ```

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

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"]
 # ~~~

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