Panel: Documentation Plan

[philippjfr]

Currently one of the major missing pieces in Panel is the lack of good structured documentation so I wanted to lay out a long-term plan. The documentation should consist of the following components:

Quickstart guide

Explains setup and basic functionality and links appropriately to the user guide (should adapt the existing user_guide/Introduction.ipynb for this purpose). Should be a single page.

User guide

This should provide an introduction to the overall design of the library and then go in-depth on different components

• [x] Overview: A high-level overview of the user guide which also serves as a glossary and quick reference for common API/features
• [x] Components: An overview of the main three components in Panel, i.e. panes, widgets and layouts, show how to use reprs, explain "reactive" behaviors, introduce linking, introduce concept of different APIs, i.e. low-level widget API, param dependency based API and interact API.
• [x] Customization: A user guide to explain the layout and styling parameters and information about CSS

Components

• Panes: What are panes? How are objects converted to a pane? How to update panes?
• Layouts: What are layouts? How does indexing and setting on layouts work? How do layout related options work (sizing_mode, max/min width/height etc.)
• Widgets: What are widgets? Basic introduction to callbacks and linking.

APIs

• Callbacks and Linking: How do you listen to parameter changes, add callbacks and links?
• Param: How to use Param to express GUI independently of Panel
• Interact: How to use Interact to express GUIs easily?

Deployment and display

• Display and Deploy: Explain the various ways to show a panel in a notebook, on the commandline and as a standalone server.
• Embedding in Django
• Embedding in Flask
• Deploying on AWS
• Deploying on Heroku
• Deploying on Google Cloud
• Deploying on Anaconda Enterprise

Gallery

The gallery should be roughly modeled on https://shiny.rstudio.com/gallery/, initially I'd expect to see the following sections:

• Showcases: Complex app examples as shown on the homepage
• Simple apps: Simpler apps with just a few widgets and plot/table/view
• Widgets: Some showcases of laying out multiple widgets, dynamically adding/disabling/updating widget state
• Layouts: Some examples showcasing how to update Column/Row/Tabs, how to replace/add a plot, how to leverage sizing_mode and other responsive layout behaviors
• Links: Demonstrate how to use JS based callbacks and links to achieve dynamic behaviors without a sever
• Embedding (once merged): Should demonstrate how to embed app state to build app without a backing python server

Reference gallery

This will simply be an overview of the different components in Panel with sections for Widgets, Panes and Layouts.

[marcosfelt]

Hi! I really like the plan above. One thing to add would be an example project.

I am just getting started with panels, and I have had quite a bit of trouble figuring out all the dependencies needed to just run the examples (e.g., jupyter, jupyterlab, holoviews, jupyter_pyviz extension etc.), so it would be nice to have a repository you could clone and a script that would set up the environment and get you running immediately.

[philippjfr]

so it would be nice to have a repository you could clone and a script that would set up the environment and get you running immediately.

Definitely a good idea, in fact I think we should have a page just for setup/installation. Things should automatically get easier once things are properly released but it's still a good idea.

[philippjfr]

I'm closing this and opening new issues.