From 03d1a576496f1f08804691f825a456d9e50ded5a Mon Sep 17 00:00:00 2001
From: Stefan Binder <binder_stefan@outlook.com>
Date: Wed, 27 Dec 2023 18:10:01 +0100
Subject: [PATCH] Docs: Add section on displaying Altair charts in dashboards
 (#3299)

* Docs: Add section on displaying Altair charts in dashboards

* Fix title line length

* Add note to changelog

* Add note about Quarto and Jupyter Book

* Change 'Some' to 'Many'

---------

Co-authored-by: Mattijn van Hoek <mattijn@gmail.com>
---
 doc/releases/changes.rst             |  1 +
 doc/user_guide/display_frontends.rst | 37 +++++++++++++++++++---------
 2 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/doc/releases/changes.rst b/doc/releases/changes.rst
index 4ef3c8397..432975514 100644
--- a/doc/releases/changes.rst
+++ b/doc/releases/changes.rst
@@ -9,6 +9,7 @@ Version 5.3.0 (unreleased month day, year)
 Enhancements
 ~~~~~~~~~~~~
 - Add "jupyter" renderer which uses JupyterChart for rendering (#3283). See :ref:`renderers` for more information.
+- Docs: Add :ref:`section on dashboards <display_dashboards>` which have support for Altair (#3299)
 - Support restrictive FIPS-compliant environment (#3291)
 
 Bug Fixes
diff --git a/doc/user_guide/display_frontends.rst b/doc/user_guide/display_frontends.rst
index 10ea5fd79..bb488986a 100644
--- a/doc/user_guide/display_frontends.rst
+++ b/doc/user_guide/display_frontends.rst
@@ -145,10 +145,33 @@ Optionally, for offline rendering, you can use the mimetype renderer::
     # Optional in VS Code
     alt.renderers.enable('mimetype')
 
+.. _display_dashboards:
+
+Dashboards
+----------
+Altair is compatible with common Python dashboarding packages. Many of them even provide support for reading out :ref:`parameters <user-guide-interactions>` from the chart.
+This allows you to e.g. select data points and update another part of the dashboard such as a table based on that selection:
+
+===================================================================================================================================  ===================================  =============================
+Package                                                                                                                              Displays interactive Altair charts   Supports reading out parameters
+===================================================================================================================================  ===================================  =============================
+`Panel <https://panel.holoviz.org/reference/panes/Vega.html#altair>`_                                                                ✔                                    ✔
+`Plotly Dash <https://dash.plotly.com/>`_ using `dash_vega_components <https://github.com/altair-viz/dash-vega-components>`_         ✔                                    ✔
+`Jupyter Voila <https://voila.readthedocs.io/en/stable/>`_ using :ref:`JupyterChart <user-guide-jupyterchart>`                       ✔                                    ✔
+`Shiny <https://shiny.posit.co/py/docs/ipywidgets.html#quick-start>`_ using :ref:`JupyterChart <user-guide-jupyterchart>`            ✔                                    ✔
+`Solara <https://solara.dev/api/altair>`_                                                                                            ✔                                    ✔
+`Streamlit <https://docs.streamlit.io/library/api-reference/charts/st.altair_chart>`_                                                ✔                                              
+===================================================================================================================================  ===================================  =============================
+
+The above mentioned frameworks all require you to run a web application on a server if you want to share your work with others. A web application gives you a lot of flexibility, you can for example fetch data from a database based on the value of a dropdown menu in the dashboard. However, it comes with some complexity as well. 
+For use cases where the interactivity provided by Altair itself is enough, you can also use tools which generate HTML pages which do not require a web server such as `Quarto <https://quarto.org/>`_ or `Jupyter Book <https://jupyterbook.org/>`_.
+
+If you are using a dashboarding package that is not listed here, please `open an issue <https://github.com/altair-viz/altair/issues>`_ on GitHub so that we can add it.
+
 .. _display-general:
 
-Working in non-Notebook Environments
-------------------------------------
+Working in environments without a JavaScript frontend
+-----------------------------------------------------   
 The Vega-Lite specifications produced by Altair can be produced in any Python
 environment, but to render these specifications currently requires a javascript
 engine. For this reason, Altair works most seamlessly with the browser-based
@@ -160,16 +183,6 @@ to a second tool that can execute javascript.
 
 There are a few options available for this:
 
-Vega-enabled IDEs
-~~~~~~~~~~~~~~~~~
-Some IDEs have extensions that natively recognize and display Altair charts.
-Examples are:
-
-- The `VSCode-Python`_ extension, which supports native Altair and Vega-Lite
-  chart display as of November 2019.
-- The Hydrogen_ project, which is built on nteract_ and renders Altair charts
-  via the ``mimetype`` renderer.
-
 Altair Viewer
 ~~~~~~~~~~~~~
 .. note::