Update docs website layout

[maximlt]

Suggestion for the new website structure:

• Adopt Diataxis
• Focus on the Reference and Gallery
• Bokeh and Matplotlib (not always though), Plotly excluded for now

Landing page

• Add link to the Getting Started
• Show how to use the website (Tutorial / How-To / Gallery / Reference / Explanation / Changelog / Contribute)

Tutorials

• Add the Getting Started
• Add more hvPlot tutorials
  • List TBD
• Link to external tutorials
  • HoloViz Tutorial

How-To

Good place to include HoloViews features (e.g. linked selections, dual axis, .opts) not yet exposed directly in hvPlot.

• List TBD

Gallery

• 1 example per card
• Mostly rather simple examples
• No need to reinvent the wheel, copy what we have, and draw inspiration from https://plotly.com/python/line-and-scatter/, https://plotly.com/python/line-and-scatter/, ...
  The majority of the subsections are plot categories (e.g. Scatter plots, Bar plots, Maps) but not limited (e.g. Interactivity, Streaming, Panel app)
  The first section is Plot types with one card per plot type (area, bar, scatter_matrix, etc.), like https://matplotlib.org/stable/plot_types/index.html
  • Define the other subsections
• Each example has link(s) to the Reference API
• Add one or more data sources when relevant (xarray as a priority, geopandas)
• Label examples with (like Demetris did on examples.holoviz.org, or with the sphinx_tags extension like Matplotlib, or custom):
  • Data type (e.g. tabular, gridded)
  • Data source (e.g. pandas, polars, xarray)
  • More?
• Two plotting backends supported: Bokeh and Matplotlib
  • One reference file assumed to be Bokeh (file per backend proved painful to maintain in HoloViews)
  • Code to convert an example to Matplotlib (e.g. adding hvplot.extension('matplotlib'), maybe more)
  • Possibility to override a Matplotlib example, declare exclusion of a Matplotlib example, only have a Matplotlib example
  • The test suite should run the Bokeh and the Matplotlib examples
  • How to display TBD (like HoloViews with multiple pages vs. each page contains the two examples, in tabs maybe)

Additional:

• Come up with and write down a procedure to generate good thumbnails

Reference

Layout:

• Installation: list all the ways hvPlot can be installed
• Integrations: list all the integrations (this page basically https://hvplot.holoviz.org/user_guide/Integrations.html)
• Generic API: register (pd.options.plotting.backend vs import hvplot.), display (save, show, extension, output, ...), help, ...
• plot/hvplot API:
  • scatter
  • line
  • text
  • explorer
  • ...
• Plot options: Tables of the plot options, each header being a link to a sub-page with plot examples
  • See below for how to potentially break down the generic options
  • Resampling / Datashading options
  • Geographic options
• Top-level plot API: andrews_curves, lag_plot, parallel_coordinates, scatter_matrix
• NetworkX API
• Explorer API
• Interactive API

Content of:

• plot/hvplot API:

  • Limited signature and docstring
  • Link to the plot options page
  • Display Bokeh and Matplotlib styling options (in tabs, Bokeh first)
  • With Bokeh only plots to display the effect of method-specific kwargs (e.g. num_bins, yerr1)
  • Links to the Gallery

• Plot options

  • Each option: name, type, default, docstring, valid for which backend (e.g. autorange not for Matplotlib)

Categories of plot options:

• Check the lists in the HoloViewsConverter class (e.g. _axis_options, _geo_options).
• Or this:

Example of subcategories for the generic options (from ChatGPT)

1. Axes and Scaling
   autorange
   flip_xaxis / flip_yaxis
   logx / logy
   logz
   loglog
   invert
   padding
   shared_axes
   sort_date
   symmetric
   check_symmetric_max
2. Color and Colormaps
   clim
   cnorm
   colorbar
   logz
   rescale_discrete_levels
   robust
3. Labels and Titles
   xlabel / ylabel / clabel
   title
   attr_labels
4. Fonts and Formatting
   fontscale
   fontsize
   legend
   rot
   xformatter / yformatter
5. Grid and Layout
   bgcolor
   grid
   frame_width / frame_height
   max_width / max_height
   min_width / min_height
   responsive
   width / height
6. Interactivity and Tools
   hover
   hover_cols
   hover_formatters
   hover_tooltips
   tools
   subcoordinate_y
   transforms
7. Ticks and Limits
   xaxis / yaxis
   xlim / ylim
   xticks / yticks / cticks

Additional:

• Need a way to construct the docstring differently compared with the normal way

Explanation

• List TBD (e.g. datashading, Statistical plots, extension)

[maximlt]

Spreadsheet to collect ideas for the Tutorials, Gallery examples and How-To guides: https://docs.google.com/spreadsheets/d/1zKaUvIi-za0Q-Unc9mPZvONnSdKericK5iXoxXlJFV0/edit?gid=1527662900#gid=1527662900