Switch to the PyData sphinx theme (#5163)

* use pydata sphinx theme to build the site

* add pooch to the docs dependencies

doc/_static/css/custom.css

@@ -0,0 +1,74 @@
+:root {
+    --pst-color-primary: 47,47,47;
+    --pst-color-link: 163,26,38;
+    --pst-color-link-hover: 254,203,56;
+}
+
+.nav-link {
+    white-space: nowrap;
+}
+
+.showcase-table {
+    border-spacing: 15px
+}
+
+.showcase-table td {
+    border: 0px;
+    vertical-align: top;
+}
+
+.pl-md-5, .px-md-5 {
+    padding-left: 1rem !important;
+}
+
+.pt-md-5, .py-md-5 {
+    padding-top: 1rem !important;
+}
+
+.cell_output {
+    padding-left: 0;
+}
+
+@media (min-width: 1200px) {
+    .container, .container-lg, .container-md, .container-sm, .container-xl {
+	max-width: 1600px;
+    }
+}
+
+#scroller-right {
+    max-width: 14%;
+}
+
+@media (max-width: 1400px) {
+    #scroller-right {
+	position: relative;
+	right: unset;
+	top: unset;
+	max-width: 100%;
+	transform: unset;
+    }
+}
+
+button.toggle-button {
+    display: none;
+}
+
+.toggle-hidden:not(.admonition) {
+    height: 0;
+}
+
+.tag_hide-input {
+    margin-bottom: 0 !important;
+}
+
+.toggle-hidden + .cell_output {
+    margin-top: 0 !important;
+}
+
+#binder-link {
+    display: inline-block;
+    font-size: 0.9rem;
+    padding-left: 1.5rem;
+    padding-top: 1rem;
+    padding-bottom: 1rem;
+}

doc/_templates/layout.html

@@ -0,0 +1,53 @@
+{%- extends "!layout.html" %}
+
+{% block docs_navbar %}
+<nav class="navbar navbar-dark navbar-expand-lg bg-dark fixed-top bd-navbar" id="navbar-main">
+  {%- include "docs-navbar.html" %}
+</nav>
+{% endblock %}
+
+{% block docs_sidebar %}
+{% if sidebars %}
+<!-- Only show if we have sidebars configured, else just a small margin  -->
+<div class="col-12 col-md-2 bd-sidebar">
+  {%- for sidebartemplate in sidebars %}
+  {%- include sidebartemplate %}
+  {%- endfor %}
+</div>
+{% else %}
+<div class="col-12 col-md-1 col-xl-2 bd-sidebar no-sidebar"></div>
+{% endif %}
+{% endblock %}
+
+{% block docs_toc %}
+<div class="d-none d-xl-block col-xl-2 bd-toc">
+  {% if meta is defined and not (meta is not none and 'notoc' in meta) %}
+  {% for toc_item in theme_page_sidebar_items %}
+  <div class="toc-item">
+    {% include toc_item %}
+  </div>
+  {% endfor %}
+  {% endif %}
+  {% if ('gallery' in pagename or 'reference' in pagename or 'user_guide' in pagename) and not pagename.endswith('index') %}
+  <a href="https://mybinder.org/v2/gh/holoviz/holoviews/{{ last_release }}?urlpath=lab/tree/examples/{{ pagename }}.ipynb" id="binder-link">Open this page in Binder</a>
+  {% endif %}
+</div>
+{% endblock %}
+
+{% block docs_main %}
+{% if sidebars %}
+{% set content_col_class = "col-md-10 col-xl-8" %}
+{% else %}
+{% set content_col_class = "col-md-11 col-xl-8" %}
+{% endif %}
+<main class="col-12 {{ content_col_class }} py-md-5 pl-md-5 pr-md-4 bd-content" role="main">
+  {% block docs_body %}
+  <div>
+    {% block body %} {% endblock %}
+  </div>
+  {% endblock %}
+  {% if theme_show_prev_next %}
+  {% include "prev-next.html" %}
+  {% endif %}
+</main>
+{% endblock %}

doc/conf.py

@@ -5,7 +5,7 @@
 # Declare information specific to this project.
 project = u'HoloViews'
 authors = u'HoloViz developers'
-copyright = u'2020 ' + authors
+copyright = u'2022 ' + authors
 description = 'Stop plotting your data - annotate your data and let it visualize itself.'
 
 import param
@@ -14,28 +14,53 @@
 param.parameterized.docstring_describe_params = False
 
 import holoviews
-version = release = holoviews.__version__
+version = release = base_version(holoviews.__version__)
 
 holoviews.extension.inline = False
 
-html_theme = 'sphinx_holoviz_theme'
+html_theme = 'pydata_sphinx_theme'
+html_logo = '_static/logo_horizontal_theme.png'
+html_favicon = '_static/favicon.ico'
+
 html_static_path += ['_static']
+
+html_css_files = [
+    'nbsite.css',
+    'css/custom.css'
+]
+
 html_theme_options = {
-    'logo': 'logo.png',
-    'favicon': 'favicon.ico',
-    'custom_css': 'holoviews.css',
-    'include_logo_text': True,
-    'second_nav': True,
-    'footer': False
+    'github_url': 'https://github.com/holoviz/holoviews',
+    'icon_links': [
+        {
+            'name': 'Twitter',
+            'url': 'https://twitter.com/holoviews',
+            'icon': 'fab fa-twitter-square',
+        },
+        {
+            'name': 'Discourse',
+            'url': 'https://discourse.holoviz.org/',
+            'icon': 'fab fa-discourse',
+        },
+    ],
+    "footer_items": [
+        "copyright",
+        "last-updated",
+    ],
+    'google_analytics_id': 'UA-61554933-1',
 }
+
 nbbuild_cell_timeout = 360
 
-extensions += ['nbsite.gallery']
+extensions += [
+    'nbsite.gallery',
+    'sphinx_copybutton',
+]
 
 nbsite_gallery_conf = {
     'backends': ['bokeh', 'matplotlib', 'plotly'],
     'galleries': {},
-    'github_org': 'pyviz',
+    'github_org': 'holoviz',
     'github_project': 'holoviews'
 }
 
@@ -60,45 +85,18 @@
         ]
     }
 
-MAIN_SITE = '//holoviews.org'
+templates_path = [
+    '_templates'
+]
 
 html_context.update({
-    'PROJECT': project,
-    'DESCRIPTION': description,
-    'AUTHOR': authors,
-    'VERSION': version,
-    'WEBSITE_URL': 'https://holoviews.org', # for canonical link
-    'GOOGLE_SEARCH_ID': '006807479272082416678:p6n_f0d8taw',
-    'GOOGLE_ANALYTICS_UA': 'UA-61554933-1',
-    # Links
-    'LINKS': (
-        ('Getting started', '/getting_started/index'),
-        ('User Guide', '/user_guide/index'),
-        ('Gallery', '/gallery/index'),
-        ('Reference Gallery', '/reference/index'),
-        ('API Docs', '/reference_manual/index'),
-        ('FAQ', '/FAQ'),
-        ('About', '/about')
-    ),
-    # About Links
-    'ABOUT': (
-        ('About', '/about.html')
-    ),
-    # Social links
-    'SOCIAL': (
-        ('Discourse', '//discourse.holoviz.org/c/holoviews'),
-        ('Twitter', '//twitter.com/holoviews'),
-        ('Github', '//github.com/pyviz/holoviews'),
-    ),
-    # Links for the docs sub navigation
-    'NAV': (
-        ('Getting started', 'getting_started/index'),
-        ('User Guide', 'user_guide/index'),
-        ('Gallery', 'gallery/index'),
-        ('Reference Gallery', 'reference/index'),
-        ('Releases', 'releases'),
-        ('API', 'reference_manual/index'),
-        ('FAQ', 'FAQ')
-    ),
-    'js_includes': html_context['js_includes']+['holoviews.js']
+    # Used to add binder links to the latest released tag.
+    'last_release': release,
+    'github_user': 'holoviz',
+    'github_repo': 'holoviews',
 })
+
+# Override the Sphinx default title that appends `documentation`
+html_title = f'{project} v{version}'
+# Format of the last updated section in the footer
+html_last_updated_fmt = '%Y-%m-%d'

doc/index.rst

@@ -69,7 +69,7 @@ If you have any `issues <https://github.com/holoviz/holoviews/issues>`_ or wish
 
 
 Installation
-____________
+------------
 
 |CondaPkg|_ |PyPI|_ |License|_ |Coveralls|_
 
@@ -133,6 +133,7 @@ After you have successfully installed and configured HoloViews, please see `Gett
    Home <self>
    Getting Started <getting_started/index>
    User Guide <user_guide/index>
+   Gallery <gallery/index>
    Reference Gallery <reference/index>
    Releases <releases>
    API <reference_manual/index>

examples/user_guide/Linking_Plots.ipynb

@@ -174,7 +174,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from holoviews.plotting.bokeh.callbacks import LinkCallback\n",
+    "from holoviews.plotting.bokeh import LinkCallback\n",
     "\n",
     "class MeanLineCallback(LinkCallback):\n",
     "\n",

setup.py

@@ -98,11 +98,13 @@
 extras_require['doc'] = extras_require['examples'] + [
     'nbsite >=0.7.1',
     'sphinx',
-    'sphinx_holoviz_theme',
     'mpl_sample_data >=3.1.3',
     'pscript',
     'graphviz',
-    'bokeh >2.2'
+    'bokeh >2.2',
+    'pydata-sphinx-theme',
+    'sphinx-copybutton',
+    'pooch',
 ]
 
 extras_require["build"] = [