holoviz / holoviz/hvplot

Update docs website layout

Open
#1,510 1 comment 0 reactions 1 assignee Claimed by @maximlt View on GitHub
Dominant language
Python
Stars
1.4k
Forks
124
Avg merge
1d 18h
Merged PRs (30d)
1

Description

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

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

## Tutorials

- [x] Add the Getting Started
- Add more hvPlot tutorials
- [ ] List TBD
- Link to external tutorials
- [x] 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:
- [x] Installation: list all the ways hvPlot can be installed
- [x] Integrations: list all the integrations (this page basically https://hvplot.holoviz.org/user_guide/Integrations.html)
- [x] Generic API: register (pd.options.plotting.backend vs import hvplot.), display (save, show, extension, output, ...), help, ...
- [x] plot/hvplot API:
- scatter
- line
- text
- explorer
- ...
- [x] 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
- [x] Top-level plot API: andrews_curves, lag_plot, parallel_coordinates, scatter_matrix
- [x] NetworkX API
- [x] Explorer API
- [ ] Interactive API

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

- Plot options
- [x] 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)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.