Doc improvements before the release (#1553)

Author: maximlt

doc/_static/custom.css

@@ -20,3 +20,9 @@
     border: 0px;
     vertical-align: top;
 }
+
+.getting-started-button {
+    border-radius: 6px !important;
+    padding: 0.7em 3em !important;
+    font-size: 1.2em;
+}

doc/_static/patch_templates/sourcelink.html

@@ -0,0 +1,9 @@
+{# Added because of https://github.com/pydata/pydata-sphinx-theme/issues/2088 #}
+{# Displays a link to the .rst source of the current page. #}
+{% if show_source and has_source and sourcename %}
+  <div class="tocsection sourcelink">
+    <a href="{{ pathto('_sources/' + sourcename, true)|e }}">
+      <i class="fa-solid fa-file-lines"></i> {{ _("Show Source") }}
+    </a>
+  </div>
+{% endif %}

doc/about.md

@@ -6,6 +6,7 @@
 
 import os
 import param
+import pydata_sphinx_theme
 
 param.parameterized.docstring_signature = False
 param.parameterized.docstring_describe_params = False
@@ -26,6 +27,10 @@
 
 html_static_path += ['_static']  # noqa
 
+if pydata_sphinx_theme.__version__ == '0.16.1':
+    # See https://github.com/pydata/pydata-sphinx-theme/issues/2088
+    templates_path.append('_static/patch_templates')  # noqa
+
 html_css_files += ['custom.css']  # noqa
 
 html_js_files = [
@@ -34,6 +39,7 @@
 
 html_theme_options.update(  # noqa
     {
+        'use_edit_page_button': True,
         'github_url': 'https://github.com/holoviz/hvplot',
         'icon_links': [
             {
@@ -57,6 +63,9 @@
     }
 )
 
+# Without this .txt is appended to the files
+html_sourcelink_suffix = ''
+
 html_theme = 'pydata_sphinx_theme'
 html_logo = '_static/logo_horizontal.svg'
 html_favicon = '_static/favicon.ico'
@@ -127,15 +136,23 @@
     'user_guide/pandas_api': 'ref/api_compatibility/pandas/pandas_api',
 }
 
+html_extra_path = ['topics.html']
+
 html_context.update(  # noqa
     {
         'last_release': f'v{release}',
-        'github_user': 'holoviz',
-        'github_repo': 'panel',
         'default_mode': 'light',
+        # Useful for the edit button
+        'github_user': 'holoviz',
+        'github_repo': 'hvplot',
+        'github_version': 'main',
+        'doc_path': 'doc',
     }
 )
 
+# linkcheck
+linkcheck_ignore = [r'https://github.com/holoviz/hvplot/pull/\d+']
+
 # mystnb
 nb_execution_excludepatterns = [
     'user_guide/Streaming.ipynb',

doc/conf.py

@@ -1680,7 +1680,7 @@
    "metadata": {},
    "source": [
     ":::{note}\n",
-    "In hvPlot, formatters can be set using format strings, by declaring bokeh `TickFormatters`, or using custom functions. See [HoloViews Tick Docs](https://holoviews.org/user_guide/Customizing_Plots.html#Axis-ticks) for more information.\n",
+    "In hvPlot, formatters can be set using format strings, by declaring bokeh `TickFormatters`, or using custom functions. See [HoloViews Tick Docs](https://holoviews.org/user_guide/Customizing_Plots.html#axis-ticks) for more information.\n",
     ":::"
    ]
   },

doc/developer_guide.md

@@ -613,7 +613,7 @@
    "id": "7c01a461-5c22-48a3-b5e1-a2a3716c5bf4",
    "metadata": {},
    "source": [
-    "`.hvplot()` supports [Intake](https://github.com/ContinuumIO/intake) `DataSource` objects."
+    "`.hvplot()` supports [Intake](https://github.com/intake/intake) `DataSource` objects."
    ]
   },
   {

doc/index.md

@@ -56,7 +56,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If the value for each section of the heatmap is pre-computed, then use `x='index'` and `y='columns'` to plot those values. Note to see how to make this same plot in bokeh, see the [bokeh docs](https://docs.bokeh.org/en/latest/docs/user_guide/categorical.html#heat-maps)."
+    "If the value for each section of the heatmap is pre-computed, then use `x='index'` and `y='columns'` to plot those values. Note to see how to make this same plot in bokeh, see the [bokeh docs](https://docs.bokeh.org/en/latest/docs/user_guide/topics/categorical.html#categorical-heatmaps)."
    ]
   },
   {

doc/ref/api/hvplot_api/hvplot.hvPlot.explorer.ipynb

@@ -0,0 +1,15 @@
+
+<html>
+    <head>
+        <noscript>
+            <meta http-equiv="refresh" content="0; url=https://examples.holoviz.org"/>
+        </noscript>
+    </head>
+    <body>
+        <script>
+            window.location.href = 'https://examples.holoviz.org' + (window.location.search || '') + (window.location.hash || '');
+        </script>
+        <p>You should have been redirected.</p>
+        <a href="https://examples.holoviz.org">If not, click here to continue.</a>
+    </body>
+</html>

doc/ref/api/index.md

@@ -79,7 +79,7 @@
    "source": [
     "## Overview\n",
     "\n",
-    "The core functionality provided by hvPlot is a **simple and high-level plotting interface** (API), modeled on [Pandas](https://pandas.pydata.org)'s `.plot` API and extended in various ways leveraging capabilities offered by the packages of the [HoloViz](https://holoviz.org) ecosystem, most notably [HoloViews](https://holoviews.org/). hvPlot can generate interactive plots with either [Bokeh](https://www.bokeh.org) (default) or [Plotly](https://plotly.com/python/), or static plots with [Matplotlib](https://matplotlib.org). hvPlot supports many data libraries of the Python ecosystem such as `pandas`, `xarray`, `dask` etc."
+    "The core functionality provided by hvPlot is a **simple and high-level plotting interface** (API), modeled on [Pandas](https://pandas.pydata.org)'s `.plot` API and extended in various ways leveraging capabilities offered by the packages of the [HoloViz](https://holoviz.org) ecosystem, most notably [HoloViews](https://holoviews.org/). hvPlot can generate interactive plots with either [Bokeh](https://bokeh.org) (default) or [Plotly](https://plotly.com/python/), or static plots with [Matplotlib](https://matplotlib.org). hvPlot supports many data libraries of the Python ecosystem such as `pandas`, `xarray`, `dask` etc."
    ]
   },
   {

doc/ref/api/hvplot_api/hvplot.hvPlot.area.ipynb renamed to doc/ref/api/manual/hvplot.hvPlot.area.ipynb

@@ -11,7 +11,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "hvPlot provides one API to explore data of many different types. Previous sections have exclusively worked with tabular data stored in pandas (or pandas-like) DataFrames. The other most common type of data are n-dimensional arrays. hvPlot aims to eventually support different array libraries but for now focuses on [xarray](https://xarray.pydata.org/en/stable/). XArray provides a convenient and very powerful wrapper to label the axis and coordinates of multi-dimensional (n-D) arrays. This user guide will cover how to leverage ``xarray`` and ``hvplot`` to visualize and explore data of different dimensionality ranging from simple 1D data, to 2D image-like data, to multi-dimensional cubes of data.\n",
+    "hvPlot provides one API to explore data of many different types. Previous sections have exclusively worked with tabular data stored in pandas (or pandas-like) DataFrames. The other most common type of data are n-dimensional arrays. hvPlot aims to eventually support different array libraries but for now focuses on [xarray](https://docs.xarray.dev/en/stable/). XArray provides a convenient and very powerful wrapper to label the axis and coordinates of multi-dimensional (n-D) arrays. This user guide will cover how to leverage ``xarray`` and ``hvplot`` to visualize and explore data of different dimensionality ranging from simple 1D data, to 2D image-like data, to multi-dimensional cubes of data.\n",
     "\n",
     "For these examples we’ll use the North American air temperature dataset:"
    ]

doc/ref/api/hvplot_api/hvplot.hvPlot.bar.ipynb renamed to doc/ref/api/manual/hvplot.hvPlot.bar.ipynb

@@ -24,7 +24,7 @@
     "* [GeoPandas](https://geopandas.org): GeoDataFrame (geometry data)\n",
     "* [NetworkX](https://networkx.github.io/documentation/stable/): Graph (network graphs)\n",
     "\n",
-    "Many of these libraries have the concept of a high-level plotting API that lets a user generate common plot types very easily. The native plotting APIs are generally built on [Matplotlib](https://matplotlib.org), which provides a solid foundation, but means that users miss out the benefits of modern, interactive plotting libraries for the web like [Bokeh](https://bokeh.pydata.org) and [HoloViews](https://holoviews.org).\n",
+    "Many of these libraries have the concept of a high-level plotting API that lets a user generate common plot types very easily. The native plotting APIs are generally built on [Matplotlib](https://matplotlib.org), which provides a solid foundation, but means that users miss out the benefits of modern, interactive plotting libraries for the web like [Bokeh](https://docs.bokeh.org) and [HoloViews](https://holoviews.org).\n",
     "\n",
     "**hvPlot** provides a high-level plotting API built on HoloViews that provides a general and consistent API for plotting data in all the formats mentioned above.\n",
     "\n",

doc/ref/api/hvplot_api/hvplot.hvPlot.barh.ipynb renamed to doc/ref/api/manual/hvplot.hvPlot.barh.ipynb

@@ -48,7 +48,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As we learned the hvPlot API closely mirrors the [Pandas plotting API](https://pandas.pydata.org/pandas-docs/stable/visualization.html), but instead of generating static images when used in a notebook, it uses HoloViews to generate either static or dynamically streaming Bokeh plots. Static plots can be used in any context, while streaming plots require a live [Jupyter notebook](https://jupyter.org), a deployed [Bokeh Server app](https://bokeh.pydata.org/en/latest/docs/user_guide/server.html), or a deployed [Panel](https://panel.holoviz.org) app.\n",
+    "As we learned the hvPlot API closely mirrors the [Pandas plotting API](https://pandas.pydata.org/pandas-docs/stable/visualization.html), but instead of generating static images when used in a notebook, it uses HoloViews to generate either static or dynamically streaming Bokeh plots. Static plots can be used in any context, while streaming plots require a live [Jupyter notebook](https://jupyter.org), a deployed [Bokeh Server app](https://docs.bokeh.org/en/latest/docs/user_guide/server.html), or a deployed [Panel](https://panel.holoviz.org) app.\n",
     "\n",
     "HoloViews provides an extensive, very rich set of objects along with a powerful set of operations to apply, as you can find out in the [HoloViews User Guide](https://holoviews.org/user_guide/index.html). But here we will focus on the most essential mechanisms needed to make your data visualizable, without having to worry about the mechanics going on behind the scenes.\n",
     "\n",

doc/ref/api/hvplot_api/hvplot.hvPlot.bivariate.ipynb renamed to doc/ref/api/manual/hvplot.hvPlot.bivariate.ipynb

@@ -54,7 +54,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As we learned the hvPlot API closely mirrors the [Pandas plotting API](https://pandas.pydata.org/pandas-docs/stable/visualization.html), but instead of generating static images when used in a notebook, it uses HoloViews to generate either static or dynamically streaming Bokeh plots. Static plots can be used in any context, while streaming plots require a live [Jupyter notebook](https://jupyter.org), a deployed [Bokeh Server app](https://bokeh.pydata.org/en/latest/docs/user_guide/server.html), or a deployed [Panel](https://panel.pyviz.org) app.\n",
+    "As we learned the hvPlot API closely mirrors the [Pandas plotting API](https://pandas.pydata.org/pandas-docs/stable/visualization.html), but instead of generating static images when used in a notebook, it uses HoloViews to generate either static or dynamically streaming Bokeh plots. Static plots can be used in any context, while streaming plots require a live [Jupyter notebook](https://jupyter.org), a deployed [Bokeh Server app](https://docs.bokeh.org/en/latest/docs/user_guide/server.html), or a deployed [Panel](https://panel.holoviz.org) app.\n",
     "\n",
     "HoloViews provides an extensive, very rich set of objects along with a powerful set of operations to apply, as you can find out in the [HoloViews User Guide](https://holoviews.org/user_guide/index.html). But here we will focus on the most essential mechanisms needed to make your data visualizable, without having to worry about the mechanics going on behind the scenes.\n",
     "\n",