Migrate user guide to how-to guides

[philippjfr]

An attempt to start migrating user guide contents to how-to and background materials.

Existing User Guides

Existing user guides were grouped

Core

• Overview: This is largely reference material, providing a high-level explanation of the component types (widgets, panes, layout), a summary of the most commonly used methods and a description of the pn.config and pn.state classes.
• Components: Again this is really reference material, providing a high-level description of the three component types.
• APIs: Goes through each API and builds the same application with it. Can easily be turned into a number of smaller API how-to guides.

Reference

• Customization: A horrible mix of reference material (e.g. describing common parameters like margin or background) and how to material (when to use which sizing mode)
• Interact: A direct copy of the ipywidgets interact docs that doesn't really fit anywhere.
• Widgets: A silly overview of widgets and a rough grouping into input, range and select widgets. No idea what to do with this.
• Parameters: A mish-mash explaining Parameterized -> Widget mappings, ParamMethod/ParamFunction and then various how-to examples on how to leverage these. Can at least partially be migrated to how-to materials.
• Linking: More mish-mash demonstrating Python and JS based linking. Some of it can become how-to material.
• Templates: Reference material plus some how-to examples.
• Pipelines: Reference material with one or two how-to examples
• Performance, Profiling and Debugging: Total mishmash of some performance tips, admin dashboard explanations etc. Can probably all become how-to material.

State, Caching & Callbacks

• Session State and Callbacks: Converted to Session state and Callbacks how-to guides.
• Asynchronous and Concurrent Processing: Started converting the async section to a Async Callbacks how-to guide. Rest should become concurrency how-to section.

Export

• Display and Export: Partially moved into export sections, display sections are closer to reference material but maybe could be rewritten to be more how-to like.
• Running Panel in the Browser with WASM: Migrated entirely to how to guides.

Server usage

Migrated cleanly to server configuration, server integrations, deployment and authentication how to guides.

Extending Panel

• Building custom components:

How-To Guide Sections

Basics

• APIs: How to use the lower and higher level APIs in Panel
  • Reactive Functions: Linking functions or methods to widgets using pn.bind or the equivalent pn.depends decorator.
  • Interact Functions: Auto-generates a full UI (including widgets) given a function.
  • Parameterized classes: Declare parameters and their ranges in Parameterized classes, then get GUIs (and value checking!) for free.
  • Callbacks: Generate a UI by manually declaring callbacks that update panels or panes.
• Using Param with Panel: Discover how to use Parameters with Panel.
  • Building UIs using Param: Discover how to generate UIs from Parameterized classes without writing any GUI related code.
  • Declare Custom Widgets: Discover how to extend Param based UIs with custom widgets.
  • Declare Parameter dependencies: Discover how to leverage @param.depends to express dependencies and trigger events based on UI interactions.
  • Param subobjects: Discover how to structure Parameterized classes with subobjects to create nested UIs automatically.
• Linking Parameters: Discover different ways of linking parameters in Python and Javascript.
  • Watchers: Discover how to use the powerful but low-level .param.watch API provided by param to trigger callbacks on parameters.
  • Links in Python: Discover how to use the convenient, high-level .link API to link parameters in Python.
  • Links in Javascript: Discover how to use the convenient, high-level .jslink API to link parameters in Javascript.
  • Link plots in Javascript: Discover how to use .jslink to link Bokeh and HoloViews plot parameters in Javascript.
  • Javascript callbacks: Discover how to use the .jscallback API to write arbitrary JS callbacks linking one or more components.

Display and Export

• Display and Preview output: How to display Panel components and apps in your favorite notebook or editor environment.
  • Display output in notebooks: How to display output in Jupyter and non-Jupyter based notebook environments.
  • Develop Apps in an Editor: Discover how to rapidly develop a Panel application in your favorite IDE or editor.
  • Develop Apps in JupyterLab: How to use the Preview functionality in JupyterLab to rapidly develop applications.
• Exporting and Saving output: How to export and save Panel applications as static files.
  • Embedding Output: How to embed the application state to share simple applications as a static file.
  • Saving output: How to save Panel applications to HTML or PNG.
  • Bokeh model: Discover how to access the Bokeh model underlying a Panel component or application
• Running in WebAssembly: How to run Panel applications entirely in the browser using WebAssembly, Pyodide and PyScript.
  • Convert to WASM: Discover how to convert existing Panel applications to WebAssembly.
  • Use from WASM: Discover how to set up and use Panel from Pyodide and PyScript.
  • Sphinx Integration: Discover how to integrate live Panel components in your Sphinx based documentation.
  • JupyterLite: Discover how to set up a JupyterLite deployment capable of rendering interactive Panel output.

Advanced

• Register Session callbacks: How to set up callbacks on session related events and periodic tasks.
  • Asynchronous Callbacks: How to leverage asynchronous callbacks to run I/O bound tasks in parallel.
  • Load callbacks: How to set up callbacks to defer a task until the application is loaded.
  • Periodic Callbacks: How to set up per-session callbacks that run periodically.
  • Session Callbacks: How to set up callbacks when a session is created and destroyed.
  • Schedule tasks: How to schedule tasks that run independently of any user visiting the application(s).
  • Bokeh server callbacks: How to safely modify Bokeh models to avoid running into issues with the Bokeh Document lock.
• Access session state: How to access state related to the user session, HTTP request and URL arguments.
  • HTTP Request: How to access information about the HTTP request associated with a session.
  • URL state: How to access and manipulate the URL.
  • Busy: How to access the busy state. (Maybe move to callbacks)
• Cache Data: How to cache data across sessions and memoize the output of functions.
  • Manual caching: How to manually cache data and objects on pn.state.cache.
  • Memoization: How to use the panel.cache decorator to memoize (i.e. cache the output of) functions automatically.
• Improve Performance: Discover some tips and tricks instructing you on how you can improve the performance of your application.
  • Splitting up layouts: Discover how splitting up layouts can help improve performance.
  • Enable throttling: Discover how to enable throttling to reduce the number of events.
• Improve Scalability: Discover various approaches telling you how to improve the scalability of your Panel application.
  • Set up Load Balancing: Discover how-to configure load balancing (e.g. using NGINX) to scale Panel apps across processes.
  • Launch multiple processes: Discover how to launch multiple processes on a Panel server to add scaling.
  • Enable Automatic Threading: Discover how to enable threading to distribute processing across threads.
  • Set up Manual Threading: Discover how to manually set up a Thread to process an event queue.
  • Use Asynchronous Processing: Discover how to make use of asynchronous callbacks to handle I/O bound operations concurrently.
• Enable Profiling & Debugging
  • Enable the Admin Panel: Discover how-to enable the admin Panel to begin monitoring resource usage and user behavior.
  • Profile your Application: Discover how to enable profilers like snakeviz or memray to track down bottlenecks in your application.
  • View Application Logs: Discover how to view application logs in the admin dashboard.

Server configuration and deployment

• Server Configuration: How to configure the Panel server.
  • Launch from the commandline: Discover how to launch and configure a Panel application from the commandline.
  • Launch programmatically: Discover how to launch and configure a Panel application programmatically.
  • Setting up a (reverse) proxy: Discover how-to configure a reverse proxy to scale your deployment.
  • Access via SSH: Discover how to access a Panel deployment running remotely via SSH.
  • Serving Static Files: Discover how to serve static files alongside your Panel application(s).
• Server Integrations: How to integrate Panel in other application based on Flask, FastAPI or Django.
  • Flask: Discover to run Panel applications alongside an existing Flask server.
  • FastAPI: Discover to run Panel applications alongside an existing FastAPI server.
  • Django: Discover to run Panel applications on a Django server (replacing the standard Tornado based server).
• Deploying applications: How to deploy Panel applications to various cloud providers (e.g. Azure, GCP, AWS etc.)
  • Azure
  • Binder
  • Google Cloud
  • Heroku
  • Hugging Face
• Authentication: How to configure OAuth to add authentication to a server deployment.
  • Configuring OAuth: Discover how to configure OAuth from the commandline.
  • OAuth Providers: A list of OAuth providers and how to configure them.
  • User Information: Discover how to make use of the user information and access tokens returned by the OAuth provider.

[philippjfr]

pre-commit.ci run

[philippjfr]

I've decided that the best thing to do to keep making progress here is to merge this PR. It's definitely not done and there's more work to do but we can track that in #3869.