Document ITables in Quarto

.github/workflows/publish-book.yml

@@ -35,6 +35,11 @@ jobs:
         pip install ipykernel
         python -m ipykernel install --name itables --user
 
+    - name: Render the quarto examples
+      uses: quarto-dev/quarto-actions/setup@v2
+      run: |
+        for qmd_file in `ls docs/quarto/*.qmd`; do quarto render ${qmd_file}; done
+
     # Build the book
     - name: Build the book
       run: |

.gitignore

@@ -18,3 +18,8 @@ _build
 
 # External dependencies
 itables/external
+
+# Quarto
+.jupyter_cache
+docs/quarto/*.html
+docs/quarto/*_files/

docs/_config.yml

@@ -2,3 +2,6 @@ title: Interactive Tables
 author: Marc Wouts
 execute:
   execute_notebooks: force
+sphinx:
+  config:
+    html_extra_path: ['quarto']

docs/_toc.yml

@@ -8,6 +8,7 @@ chapters:
 - file: downsampling
 - file: sample_dataframes
 - file: polars_dataframes
+- file: quarto
 - file: references
 - file: contributing
 - file: developing

docs/changelog.md

@@ -13,6 +13,10 @@ ITables ChangeLog
 - In the offline mode, the datatables.net library is now loaded when the table is displayed. This is expected to improve the VSCode experience ([#216](https://github.com/mwouts/itables/issues/216))
 - We have removed the `.itables` class. Please use `.dataTables_wrapper` in your CSS instead.
 
+**Added**
+- We have added a section on Quarto in the documentation ([#179](https://github.com/mwouts/itables/issues/179))
+
+
 1.6.4 (2024-02-03)
 ------------------
 

docs/quarto.md

@@ -0,0 +1,31 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.14.5
+kernelspec:
+  display_name: itables
+  language: python
+  name: itables
+---
+
+# Quarto
+
+ITables works well with the `revealjs` and `html` outputs formats of [Quarto](https://quarto.org).
+
+## HTML Presentations
+
+See this <a href="quarto_revealjs.html">revealjs presentation</a>,
+or download the <a href="quarto_revealjs.qmd">source file</a> and render it with `quarto render`:
+
+<iframe src=quarto_revealjs.html width="750px" height="500px"></iframe>
+
+## HTML reports
+
+See this <a href="quarto_html.html">HTML report</a>,
+or download the <a href="quarto_html.qmd">source file</a> and render it with `quarto render`:
+
+<iframe src=quarto_html.html width="100%" height="600px"></iframe>

docs/quarto/quarto_html.qmd

@@ -0,0 +1,133 @@
+---
+title: ITables in Quarto
+subtitle: Interactive Tables in HTML reports
+standalone: true
+format:
+  html:
+    html-table-processing: none
+    code-line-numbers: false
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .qmd
+      format_name: quarto
+      format_version: '1.0'
+      jupytext_version: 1.16.1
+  kernelspec:
+    display_name: itables
+    language: python
+    name: itables
+---
+
+## How to use ITables in Quarto
+
+::: {.callout-note}
+## Activate ITables (as in Jupyter, VS Code, PyCharm, Google Colab!)
+
+```{python}
+#| echo: false
+
+import itables.options as opt
+
+# show 5 rows per 'page'
+opt.lengthMenu = [5]
+
+# don't show the length control
+opt.dom = "frtip"
+
+# use a smaller font (default is medium)
+# see https://developer.mozilla.org/en-US/docs/Web/CSS/font-size
+opt.css += ".dataTables_wrapper { font-size: small; }"
+```
+
+```{python}
+#| echo: true
+
+from itables import init_notebook_mode
+
+init_notebook_mode(all_interactive=True)
+```
+:::
+
+```{python}
+#| echo: true
+#| code-fold: true
+#| code-summary: "... and all DataFrames become interactive!"
+from itables.sample_dfs import get_countries
+
+get_countries(html=False)
+```
+
+## How to make my table fit in the report?
+
+::: {.callout-tip}
+## How to make your table smaller
+
+- display only a few rows with `lengthMenu`,
+- adjust the [style or font](https://mwouts.github.io/itables/custom_css.html) with a custom `css`
+:::
+
+::: {.callout-note}
+## This document uses
+
+```python
+import itables.options as opt
+
+
+# show 5 rows per 'page'
+opt.lengthMenu = [5]
+
+# don't show the length control
+opt.dom = "frtip"
+
+# use a smaller font (default is medium)
+# see https://developer.mozilla.org/en-US/docs/Web/CSS/font-size
+opt.css += ".dataTables_wrapper { font-size: x-small; }"
+```
+:::
+
+## Advanced Parameters
+
+::: {.callout-tip}
+## Parameters
+
+ITables' [advanced parameters](https://mwouts.github.io/itables/advanced_parameters.html):
+
+- Can be set globally on `opt`, or
+- Passed as arguments to the `show` function.
+- Table-specific arguments like [caption](https://mwouts.github.io/itables/advanced_parameters.html#caption) are only available in `show`.
+:::
+
+::: {.callout-warning}
+## Global Options and Quarto's cache
+
+Quarto uses a cache that may prevent your changes on `itables.options` to become effective
+when you run `quarto render`.
+
+In that case, use `--cache-refresh` or even `--execute-daemon-restart`.
+:::
+
+## About ITables
+
+::: {.callout-note}
+## GitHub <a class="github-button" href="https://github.com/mwouts/itables" data-icon="octicon-star" data-show-count="true" aria-label="Star mwouts/itables on GitHub">Star</a>
+
+ITables is developed by [Marc Wouts](https://github.com/mwouts) on [GitHub](https://github.com/mwouts/itables),
+under a MIT license.
+
+<script async defer src="https://buttons.github.io/buttons.js"></script>
+:::
+
+::: {.callout-tip}
+## Under the hood
+
+ITables renders Pandas or Polars DataFrames as
+interactive HTML tables using the JavaScript
+[datatables-net](https://datatables.net/) library.
+:::
+
+::: {.callout-tip}
+## Documentation
+
+Learn More about ITables in the [documentation](https://mwouts.github.io/itables).
+:::

docs/quarto/quarto_revealjs.qmd

@@ -0,0 +1,133 @@
+---
+title: ITables in Quarto
+subtitle: Interactive Tables in HTML presentations
+standalone: true
+format:
+  revealjs:
+    html-table-processing: none
+    code-line-numbers: false
+jupyter:
+  jupytext:
+    text_representation:
+      extension: .qmd
+      format_name: quarto
+      format_version: '1.0'
+      jupytext_version: 1.16.1
+  kernelspec:
+    display_name: itables
+    language: python
+    name: itables
+---
+
+## How to use ITables in Quarto
+
+::: {.callout-note}
+## Activate ITables (as in Jupyter, VS Code, PyCharm, Google Colab!)
+
+```{python}
+#| echo: false
+
+import itables.options as opt
+
+# show 5 rows per 'page'
+opt.lengthMenu = [5]
+
+# don't show the length control
+opt.dom = "frtip"
+
+# use a smaller font (default is medium)
+# see https://developer.mozilla.org/en-US/docs/Web/CSS/font-size
+opt.css += ".dataTables_wrapper { font-size: small; }"
+```
+
+```{python}
+#| echo: true
+
+from itables import init_notebook_mode
+
+init_notebook_mode(all_interactive=True)
+```
+:::
+
+```{python}
+#| echo: true
+#| code-fold: true
+#| code-summary: "... and all DataFrames become interactive!"
+from itables.sample_dfs import get_countries
+
+get_countries(html=False)
+```
+
+## How to make my table fit in one slide?
+
+::: {.callout-tip}
+## How to make your table smaller
+
+- display only a few rows with `lengthMenu`,
+- adjust the [style or font](https://mwouts.github.io/itables/custom_css.html) with a custom `css`
+:::
+
+::: {.callout-note}
+## This document uses
+
+```python
+import itables.options as opt
+
+
+# show 5 rows per 'page'
+opt.lengthMenu = [5]
+
+# don't show the length control
+opt.dom = "frtip"
+
+# use a smaller font (default is medium)
+# see https://developer.mozilla.org/en-US/docs/Web/CSS/font-size
+opt.css += ".dataTables_wrapper { font-size: small; }"
+```
+:::
+
+## Advanced Parameters
+
+::: {.callout-tip}
+## Parameters
+
+ITables' [advanced parameters](https://mwouts.github.io/itables/advanced_parameters.html):
+
+- Can be set globally on `opt`, or
+- Passed as arguments to the `show` function.
+- Table-specific arguments like [caption](https://mwouts.github.io/itables/advanced_parameters.html#caption) are only available in `show`.
+:::
+
+::: {.callout-warning}
+## Global Options and Quarto's cache
+
+Quarto uses a cache that may prevent your changes on `itables.options` to become effective
+when you run `quarto render`.
+
+In that case, use `--cache-refresh` or even `--execute-daemon-restart`.
+:::
+
+## About ITables
+
+::: {.callout-note}
+## GitHub <a class="github-button" href="https://github.com/mwouts/itables" data-icon="octicon-star" data-show-count="true" aria-label="Star mwouts/itables on GitHub">Star</a>
+
+ITables is developed by [Marc Wouts](https://github.com/mwouts) on [GitHub](https://github.com/mwouts/itables),
+under a MIT license.
+
+<script async defer src="https://buttons.github.io/buttons.js"></script>
+:::
+
+::: {.callout-tip}
+## Under the hood
+
+ITables renders Pandas or Polars DataFrames as
+interactive HTML tables using the JavaScript
+[datatables-net](https://datatables.net/) library.
+:::
+
+::: {.callout-tip}
+## Documentation
+
+Learn More about ITables in the [documentation](https://mwouts.github.io/itables).
+:::

docs/supported_editors.md

@@ -43,6 +43,10 @@ because otherwise the notebooks do not display the interactive tables when they
 
 ![](images/pycharm.png)
 
+## Quarto
+
+ITables works well with the HTML formats of Quarto, see our [examples](quarto.md).
+
 # Exporting a DataFrame to an HTML table
 
 To get the HTML representation of a Pandas DataFrame `df` as an interactive [datatable](https://datatables.net/), you can use `to_html_datatable` as below:

itables/html/itables.css

@@ -19,3 +19,6 @@
     padding: 3px;
     box-sizing: border-box;
 }
+
+/* We set an explicit size otherwise the font is too big in Quarto */
+.dataTables_wrapper { font-size: medium; }

itables/version.py

@@ -1,3 +1,3 @@
 """ITables' version number"""
 
-__version__ = "1.7.0-dev"
+__version__ = "1.7.0"