Reorganize about and api sections

holoviz · philippjfr · Jan 5, 2023 · Jan 3, 2023 · Jan 3, 2023 · Jan 3, 2023
commit d4d53469b205e33c927e6fd95769ece10e453ab2
diff --git a/doc/about/comparisons.rst → doc/about/comparisons.md b/doc/about/comparisons.rst → doc/about/comparisons.md
@@ -1,9 +1,6 @@
-Comparisons
-===========
+# Comparisons
 
-
-Comparing Panel and Bokeh
--------------------------
+## Comparing Panel and Bokeh
 
 Panel and Bokeh can both be used to create dashboards in Python, but are intended for different uses and different audiences:
 
@@ -14,9 +11,7 @@ Panel and Bokeh can both be used to create dashboards in Python, but are intende
 - Bokeh focuses on providing lower-level primitives that can be used to create any dashboard with enough effort, while Panel focuses on making common data-science tasks and making typical types of apps easier.
 
 
-
-Comparing Panel and Dash
-------------------------
+## Comparing Panel and Dash
 
 Panel and Dash can both be used to create dashboards in Python, but take very different approaches:
 
@@ -33,8 +28,7 @@ Panel and Dash can both be used to create dashboards in Python, but take very di
   * Panel's approach makes it easy to do server-side caching of intermediate computations for each user, which can make complex processing pipelines much more responsive. For instance, when used with a Datashader pipeline where the server renders an image from data that is never transmitted to the client, only the stages that have actually changed need to be re-run when a user interacts with the plot, making rendering changes like selecting a colormap almost instantaneous because the already aggregated data can be reused. With Dash, the server does not retain a copy of the intermediate data in such a pipeline, so when a new request comes in, it has to recompute each of the stages even when the data involved has not changed.  The `Datashader example dashboard <https://examples.pyviz.org/datashader_dashboard/dashboard.html>`__ shows how to use this intermediate-value caching to provide the fastest possible updates for a given user action, only re-running the computation actually needed to satisfy the request, re-using cached values stored on the server when appropriate.
 
 
-Comparing Panel and ipywidgets
-------------------------------
+## Comparing Panel and ipywidgets
 
 Both Panel and ipywidgets (aka Jupyter Widgets) allow Python users to work with custom widgets and create apps and dashboards from Python, both in Jupyter notebooks and in standalone servers (when paired with Voila). But Panel and ipywidgets are based on different, independently developed technologies for doing so, with some implications:
 
@@ -51,9 +45,7 @@ Both Panel and ipywidgets (aka Jupyter Widgets) allow Python users to work with
 - As of 9/2020, both types of widgets are now fully interoperable; you can use Panel or Bokeh widgets and panes in an ipywidgets-based app using `jupyter_bokeh <https://github.com/bokeh/jupyter_bokeh>`_ and you can use ipywidgets in a Panel or Bokeh app using `ipywidgets_bokeh <https://github.com/bokeh/ipywidgets_bokeh>`_.  So in practice, you can now mix and match content from either ecosystem as needed, choosing your "native" ecosystem based on other factors like deployment options (see below).
 
 
-
-Comparing Panel and Voila
--------------------------
+## Comparing Panel and Voila
 
 Voila is a technology for deploying Jupyter notebooks (with or without Panel code) as standalone web pages backed by Python. Voila is thus one way you can deploy your Panel apps, your ipywidgets-based apps, or any other content visible in a Jupyter notebook (including multiple languages, like R or C++). Voila is an alternative to the Bokeh Server component that is available through ``panel serve``; Panel works with either one, and you can deploy with *either* Bokeh Server (panel serve) or Voila. To serve a Panel app with Voila, just install `jupyter_bokeh <https://github.com/bokeh/jupyter_bokeh>`__ and do ``pn.ipywidget(panel_obj)``, which makes an ipywidget out of your Panel object that Voila (or Jupyter itself) can then display and let you interact with.
 
@@ -70,8 +62,7 @@ The other major difference between Bokeh Server and Voila is the way they proces
 Panel takes a different approach, in that output from a notebook cell needs to be explicitly wrapped in a Panel object and marked as being "servable"; cell outputs and Markdown cells by default are shown only in the notebook, and not with ``panel serve``. Panel in fact entirely ignores the fact that your notebook is organized into cells; it simply processes all the cells as Python code, and serves all the items that ended up being marked "servable". Although this approach means editing the original notebook before you can see a dashboard, it makes it fully practical for the same notebook to serve both an exploratory or storytelling purpose (in Jupyter) and act as a dashboard deployment (of a designated subset of the functionality). The Panel developers very often use this functionality to provide detailed documentation for any given panel, with the cell-by-cell output showing the dataset, intermediate steps, interesting features, and how-tos, while the final deployed dashboard focuses on the final result, with the content in each case organized to best suit its purpose.
 
 
-Comparing Panel and streamlit
------------------------------
+## Comparing Panel and streamlit
 
 streamlit is an alternative to all of the above packages. Like Jupyter, streamlit provides an interactive, incremental way to build apps. streamlit works with Python text files written in a separate editor, while Jupyter uses a web-based notebook cell editor. Although a web-based editor makes it simple to work locally on remote files, using a local Python text file allows users to maximize their productivity by choosing their own favorite editor. Dash, Panel, and Bokeh all also support bare Python files developed in a local editor, and like streamlit they can all also watch that file and automatically re-run the file when you change it in the editor (e.g. for Panel or Bokeh, launch ``bokeh serve file.py --dev`` to watch the Python file and re-launch the served app on any changes).
 

diff --git a/doc/about/index.md b/doc/about/index.md
@@ -0,0 +1,19 @@
+# About
+
+Panel is completely open source, available under a BSD license freely for both commercial and non-commercial use. Panel was originally developed with the support of [Anaconda Inc.](https://anaconda.com) using funding f
10BC0
rom various commercial and government partners, and is now maintained by Anaconda developers and community contributors.
+
+Panel is part of the [HoloViz](https://holoviz.org) family of tools. The [holoviz.org](https://holoviz.org) website shows how to use Panel together with other libraries to solve complex problems, with detailed tutorials and examples. You can see a variety of projects using Panel at [examples.pyviz.org](https://examples.pyviz.org), and you can compare Panel to other available tools at [pyviz.org](https://pyviz.org).
+
+If you have any questions or usage issues visit the [Panel Discourse](https://discourse.holoviz.org/c/panel/) site. If you are interested in contributing to Panel development to help address some of the [open issues](https://github.com/holoviz/panel/issues), see our [developer instructions](https://pyviz-dev.github.io/panel/developer_guide/index.html) to set up your development environment.
+
+If you like Panel and have built something you want to share, tweet a link or screenshot of your latest creation at @Panel_org, along with any other library you used (@HoloViews, @Datashader, @BokehPlots, @Matplotlib, etc.). Thanks!
+
+
+```{toctree}
+:titlesonly:
+:hidden:
+:maxdepth: 2
+
+releases
+comparisons
+```
diff --git a/doc/about/index.rst b/doc/about/index.rst
diff --git a/doc/releases.md → doc/about/releases.md b/doc/releases.md → doc/about/releases.md
diff --git a/doc/user_guide/Overview.md → doc/api/cheatsheet.md b/doc/user_guide/Overview.md → doc/api/cheatsheet.md
@@ -1,4 +1,4 @@
-# Overview
+# Cheat Sheet
 
 In order to get the best use out of the Panel user guide, it is important to have a grasp of some core concepts, ideas, and terminology.
 
@@ -131,85 +131,3 @@ One of the most important aspects of a general app and dashboarding framework is
 #### ``.jslink()``
 
 > The JavaScript-based ``.jslink()`` method directly links properties of the underlying Bokeh models, making it possible to define interactivity that works even without a running Python server.
-
-___
-
-## State and configuration
-
-Panel provides top-level objects to hold current state and control high-level configuration variables.
-
-### `pn.config`
-
-The `pn.config` object allows setting various configuration variables, the config variables can also be set as environment variables or passed through the [`pn.extension`](#pn-extension):
-
-#### Python only
-
-> - `css_files`: External CSS files to load.
-> - `js_files`: External JS files to load. Dictionary should map from exported name to the URL of the JS file.
-> - `loading_spinner`: The style of the global loading indicator, e.g. 'arcs', 'bars', 'dots', 'petals'.
-> - `loading_color`: The color of the global loading indicator as a hex color, e.g. #6a6a6a
-> - `defer_load`: Whether reactive function evaluation is deferred until the page is rendered.
-> - `exception_handler`: A custom exception handler can be defined which should accept any exceptions raised while processing events originating from the frontend and onload callbacks.
-> - `nthreads`: If set will start a `ThreadPoolExecutor` to dispatch events to for concurrent execution on separate cores. By default no thread pool is launched, while setting nthreads=0 launches `min(32, os.cpu_count() + 4)` threads.
-> - `raw_css`: List of raw CSS strings to add to load.
-> - `reuse_sessions`: Whether to reuse a session for the initial request to speed up the initial page render. Note that if the initial page differs between sessions, e.g. because it uses query parameters to modify the rendered content, then this option will result in the wrong content being rendered. See the [Performance and Debugging guide](Performance_and_Debugging.rst#Reuse-sessions) for more information.
-> - `safe_embed`: Whether to record all set events when embedding rather than just those that are changed
-> - `session_history`: If set to a non-zero value this determines the maximum length of the pn.state.session_info dictionary, which tracks information about user sessions. A value of -1 indicates an unlimited history.
-> - `sizing_mode`:  Specify the default sizing mode behavior of panels.
-> - `template`: The template to render the served application into, e.g. `'bootstrap'` or `'material'`.
-> - `theme`: The theme to apply to the selected template (no effect unless `template` is set)
-> - `throttled`: Whether sliders and inputs should be throttled until release of mouse.
-
-#### Python and Environment variables
-
-> - `comms` (`PANEL_COMMS`): Whether to render output in Jupyter with the default Jupyter extension or use the `jupyter_bokeh` ipywidget model.
-> - `console_output` (`PANEL_CONSOLE_OUTPUT`): How to log errors and stdout output triggered by callbacks from Javascript in the notebook. Options include `'accumulate'`, `'replace'` and `'disable'`.
-> - `embed` (`PANEL_EMBED`): Whether plot data will be [embedded](./Deploy_and_Export.rst#Embedding).
-> - `embed_json` (`PANEL_EMBED_JSON`): Whether to save embedded state to json files.
-> - `embed_json_prefix` (`PANEL_EMBED_JSON_PREFIX`): Prefix for randomly generated json directories.
-> - `embed_load_path` (`PANEL_EMBED_LOAD_PATH`): Where to load json files for embedded state.
-> - `embed_save_path` (`PANEL_EMBED_SAVE_PATH`): Where to save json files for embedded state.
-> - `inline` (`PANEL_INLINE`): Whether to inline JS and CSS resources. If disabled, resources are loaded from CDN if one is available.
-> - `npm_cdn` (`PANEL_NPM_CDN`): The CDN to load NPM packages from if resources are served from CDN. Allows switching between 'https://unpkg.com' (default) and 'https://cdn.jsdelivr.net/npm' for most resources.
-
-#### `pn.state`
-
-The `pn.state` object makes various global state available and provides methods to manage that state:
-
-- - `access_token`: The access token issued by the OAuth provider to authorize requests to its APIs.
-> - `busy`: A boolean value to indicate whether a callback is being actively processed.
-> - `cache`: A global cache which can be used to share data between different processes.
-> - `cookies`: HTTP request cookies for the current session.
-> - `curdoc`: When running a server session this property holds the current bokeh Document.
-> - `location`: In a server context this provides read and write access to the URL:
->   * `hash`: hash in window.location e.g. '#interact'
->   * `pathname`: pathname in window.location e.g. '/user_guide/Interact.html'
->   * `search`: search in window.location e.g. '?color=blue'
->   * `reload`: Reloads the page when the location is updated.
->   * `href` (readonly): The full url, e.g. 'https://localhost:80?color=blue#interact'
->   * `hostname` (readonly): hostname in window.location e.g. 'panel.holoviz.org'
->   * `protocol` (readonly): protocol in window.location e.g. 'http:' or 'https:'
->   * `port` (readonly): port in window.location e.g. '80'
-> - `headers`: HTTP request headers for the current session.
-> - `refresh_token`: The refresh token issued by the OAuth provider to authorize requests to its APIs (if available these are usually longer lived than the `access_token`).
-> - `session_args`: When running a server session this return the request arguments.
-> - `session_info`: A dictionary tracking information about server sessions:
->   * `total` (int): The total number of sessions that have been opened
->   * `live` (int): The current number of live sessions
->   * `sessions` (dict(str, dict)): A dictionary of session information:
->       * `started`: Timestamp when the session was started
->       * `rendered`: Timestamp when the session was rendered
->       * `ended`: Timestamp when the session was ended
->       * `user_agent`: User-Agent header of client that opened the session
-> - `webdriver`: Caches the current webdriver to speed up export of bokeh models to PNGs.
->
-> #### Methods
->
-> - `add_periodic_callback`: Schedules a periodic callback to be run at an interval set by the period
-> - `as_cached`: Allows caching data across sessions by memoizing on the provided key and keyword arguments to the provided function.
-> - `cancel_scheduled`: Cancel a scheduled task by name.
-> - `execute`: Executes both synchronous and asynchronous callbacks appropriately depending on the context the application is running in.
-> - `kill_all_servers`: Stops all running server sessions.
-> - `onload`: Allows defining a callback which is run when a server is fully loaded
-> - `schedule`: Schedule a callback periodically at a specific time (click [here](./Deploy_and_Export.rst#pn.state.schedule) for more details)
-> - `sync_busy`: Sync an indicator with a boolean value parameter to the busy property on state
diff --git a/doc/api/config.md b/doc/api/config.md
@@ -0,0 +1,76 @@
+# Config
+
+The `pn.config` object allows setting various configuration variables, the config variables can also be set as environment variables or passed through the [`pn.extension`](cheatsheet#pn-extension):
+
+### Python only
+
+`css_files`
+: External CSS files to load.
+
+`js_files`
+: External JS files to load. Dictionary should map from exported name to the URL of the JS file.
+
+`loading_spinner`
+: The style of the global loading indicator, e.g. 'arcs', 'bars', 'dots', 'petals'.
+
+`loading_color`
+: The color of the global loading indicator as a hex color, e.g. #6a6a6a
+
+`defer_load`
+: Whether reactive function evaluation is deferred until the page is rendered.
+
+`exception_handler`
+: A custom exception handler can be defined which should accept any exceptions raised while processing events originating from the frontend and onload callbacks.
+
+`nthreads`
+: If set will start a `ThreadPoolExecutor` to dispatch events to for concurrent execution on separate cores. By default no thread pool is launched, while setting nthreads=0 launches `min(32, os.cpu_count() + 4)` threads.
+
+`raw_css`
+: List of raw CSS strings to add to load.
+
+`reuse_sessions`
+: Whether to reuse a session for the initial request to speed up the initial page render. Note that if the initial page differs between sessions, e.g. because it uses query parameters to modify the rendered content, then this option will result in the wrong content being rendered. See the [Performance and Debugging guide](Performance_and_Debugging.rst#Reuse-sessions) for more information.
+
+`safe_embed`
+: Whether to record all set events when embedding rather than just those that are changed
+
+`session_history`
+: If set to a non-zero value this determines the maximum length of the pn.state.session_info dictionary, which tracks information about user sessions. A value of -1 indicates an unlimited history.
+`sizing_mode`
+:  Specify the default sizing mode behavior of panels.
+
+`template`
+: The template to render the served application into, e.g. `'bootstrap'` or `'material'`.
+
+`theme`
+: The theme to apply to the selected template (no effect unless `template` is set)
+
+`throttled`
+: Whether sliders and inputs should be throttled until release of mouse.
+
+### Python and Environment variables
+
+`comms` (`PANEL_COMMS`)
+: Whether to render output in Jupyter with the default Jupyter extension or use the `jupyter_bokeh` ipywidget model.
+`console_output` (`PANEL_CONSOLE_OUTPUT`): How to log errors and stdout output triggered by callbacks from Javascript in the notebook. Options include `'accumulate'`, `'replace'` and `'disable'`.
+
+`embed` (`PANEL_EMBED`)
+: Whether plot data will be [embedded](./Deploy_and_Export.rst#Embedding).
+
+`embed_json` (`PANEL_EMBED_JSON`)
+: Whether to save embedded state to json files.
+
+`embed_json_prefix` (`PANEL_EMBED_JSON_PREFIX`)
+: Prefix for randomly generated json directories.
+
+`embed_load_path` (`PANEL_EMBED_LOAD_PATH`)
+: Where to load json files for embedded state.
+
+`embed_save_path` (`PANEL_EMBED_SAVE_PATH`)
+: Where to save json files for embedded state.
+
+`inline` (`PANEL_INLINE`)
+: Whether to inline JS and CSS resources. If disabled, resources are loaded from CDN if one is available.
+
+`npm_cdn` (`PANEL_NPM_CDN`)
+: The CDN to load NPM packages from if resources are served from CDN. Allows switching between 'https://unpkg.com' (default) and 'https://cdn.jsdelivr.net/npm' for most resources.