Refresh documentation styling with Furo theme

CHANGELOG.md

@@ -28,6 +28,7 @@ This release is compatible with NumPy 2.5.
 * Allowed `dpnp.take` and `dpnp.compress` to cast the result into an `out` array of a different but same-kind dtype [#2959](https://github.com/IntelPython/dpnp/pull/2959)
 * Clarified the summary in `dpnp.reshape` and `dpnp.ndarray.reshape` docstrings [#2964](https://github.com/IntelPython/dpnp/pull/2964)
 * Changed `dpnp.atleast_1d`, `dpnp.atleast_2d`, `dpnp.atleast_3d`, and `dpnp.ogrid` to return a tuple of arrays instead of a list [#2965](https://github.com/IntelPython/dpnp/pull/2965)
+* Refreshed `dpnp` documentation styling with the Furo theme [#2934](https://github.com/IntelPython/dpnp/pull/2934)
 
 ### Deprecated
 

doc/_static/dpnp-custom.css

@@ -0,0 +1,70 @@
+/* Autosummary tables: left-aligned */
+.longtable.docutils {
+    margin-left: 0;
+    margin-right: auto;
+}
+
+/* Admonitions: normal font size, no left accent bar */
+div.admonition {
+    font-size: inherit !important;
+    border-left: 0 !important;
+}
+
+/* Table borders and alternating row backgrounds */
+body table.docutils td,
+body table.docutils th {
+    border: 1px solid var(--color-foreground-border) !important;
+    padding: 8px 12px;
+}
+
+body table.docutils thead th,
+body table.docutils tbody tr.row-odd {
+    background-color: var(--color-background-secondary) !important;
+}
+
+body table.docutils tbody tr.row-even {
+    background: transparent !important;
+}
+
+/* Docstring section titles: normal case, bold, secondary background */
+dd p.rubric,
+dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list > dt,
+.admonition > .admonition-title {
+    text-transform: none !important;
+    font-size: inherit !important;
+    font-weight: 700 !important;
+    background-color: var(--color-background-secondary);
+    padding: 4px 8px;
+}
+
+/* Constants page: lighter section headers */
+#constants dd p.rubric {
+    background-color: transparent;
+    padding: 0;
+    border-bottom: 1px solid var(--color-foreground-border);
+}
+
+/* Function signatures: normal weight, bold only for name and param names */
+dt.sig.sig-object,
+dt.sig.sig-object * {
+    font-weight: 400 !important;
+}
+
+dt.sig.sig-object .sig-name,
+dt.sig.sig-object .sig-name *,
+dt.sig.sig-object .sig-param > .n,
+dt.sig.sig-object .sig-param > .n * {
+    font-weight: 700 !important;
+}
+
+/* Parameter/return descriptions: indented block on new line (via custom.js) */
+dl.field-list dd .param-desc {
+    display: block;
+    padding-left: 1.5em;
+}
+
+/* Parameter lists: no bullets, keep indentation */
+dl.field-list dd ul.simple {
+    list-style: none !important;
+    padding-left: 1.2em !important;
+}

doc/_static/dpnp-custom.js

@@ -0,0 +1,67 @@
+(function() {
+var separators = [ " – ", " -- " ];
+
+function findSeparator(container)
+{
+    var walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
+    var node;
+    while ((node = walker.nextNode())) {
+        for (var i = 0; i < separators.length; i++) {
+            var idx = node.nodeValue.indexOf(separators[i]);
+            if (idx !== -1)
+                return {node : node, offset : idx, sep : separators[i]};
+        }
+    }
+    return null;
+}
+
+// Splits <p> at the separator; wraps everything after it in .param-desc.
+function reformatP(p)
+{
+    var found = findSeparator(p);
+    if (!found)
+        return null;
+
+    var afterNode = found.node.splitText(found.offset);
+    afterNode.nodeValue = afterNode.nodeValue.slice(found.sep.length);
+
+    var range = document.createRange();
+    range.setStartBefore(afterNode);
+    range.setEndAfter(p.lastChild);
+
+    var desc = document.createElement("span");
+    desc.className = "param-desc";
+    desc.appendChild(range.extractContents());
+    p.appendChild(desc);
+    return desc;
+}
+
+// Browsers auto-close nested <p> tags, so multi-paragraph descriptions
+// arrive as sibling <p> elements inside <li>. Fold them into the same desc.
+function reformatEntry(container)
+{
+    var firstP = container.querySelector(":scope > p");
+    if (!firstP)
+        return;
+
+    var desc = reformatP(firstP);
+    if (!desc)
+        return;
+
+    var sibling;
+    while ((sibling = firstP.nextElementSibling) && sibling.tagName === "P") {
+        if (desc.textContent.trim())
+            desc.appendChild(document.createElement("br"));
+        while (sibling.firstChild)
+            desc.appendChild(sibling.firstChild);
+        sibling.remove();
+    }
+}
+
+document.querySelectorAll("dl.field-list dd ul.simple li")
+    .forEach(reformatEntry);
+document.querySelectorAll("dl.field-list dd").forEach(function(dd) {
+    if (!dd.querySelector("ul.simple"))
+        reformatEntry(dd);
+});
+}());

doc/conf.py

@@ -45,9 +45,8 @@
 copyright = f"2020-{year}, Intel Corporation"
 author = "Intel"
 
-version = dpnp.__version__.strip(".dirty")
-# The full version, including alpha/beta/rc tags
-release = dpnp.__version__.strip(".dirty")
+# Strip local version identifiers (e.g. git hash) from the version string
+version = release = dpnp.__version__.split("+")[0]
 
 
 # -- General configuration ---------------------------------------------------
@@ -68,10 +67,15 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx_copybutton",
+    "sphinx_design",
     "sphinxcontrib.googleanalytics",
     "sphinxcontrib.spelling",
 ]
 
+copybutton_prompt_text = r">>> |\.\.\. "
+copybutton_prompt_is_regexp = True
+
 googleanalytics_id = "G-554F8VNE28"
 googleanalytics_enabled = True
 
@@ -106,31 +110,28 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = "default"
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
-html_theme = "sphinx_rtd_theme"
-html_theme_options = {
-    "sidebarwidth": 30,
-    "nosidebar": False,
-}
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
+html_theme = "furo"
+# TODO: Remove html_title and uncomment html_logo once dpnp.svg is available
+html_title = f"Data Parallel Extension for NumPy (dpnp) {release} documentation"
+html_theme_options = {}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ["_static"]
+
+# html_logo = "_static/dpnp.svg"
+# html_favicon = "_static/dpnp.svg"
+html_css_files = ["dpnp-custom.css"]
+html_js_files = ["dpnp-custom.js"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -140,15 +141,6 @@
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
 #
-# html_sidebars = {}
-html_sidebars = {
-    "**": [
-        "globaltoc.html",
-        "relations.html",
-        "sourcelink.html",
-        "searchbox.html",
-    ]
-}
 
 
 # -- Options for HTMLHelp output ---------------------------------------------

doc/ext_links.txt

@@ -4,6 +4,7 @@
     **********************************************************
 
 .. _NumPy*: https://numpy.org/
+.. _SciPy*: https://scipy.org/
 .. _Python* Array API Standard: https://data-apis.org/array-api/
 .. _OpenCl*: https://www.khronos.org/opencl/
 .. _oneAPI Level Zero: https://spec.oneapi.io/level-zero/latest/index.html

doc/index.rst

@@ -1,14 +1,99 @@
 .. _index:
 .. include:: ./ext_links.txt
 
+===================================
 Data Parallel Extension for NumPy*
-==================================
+===================================
 
 .. module:: dpnp
     :no-index:
 
+:py:mod:`dpnp` is a NumPy-compatible array library for data-parallel
+computing. It acts as a drop-in replacement for core `NumPy*`_ functions
+and numerical data types and provides implementations of selected
+`SciPy*`_ routines for data-parallel devices.
+
+.. grid:: 2
+    :gutter: 3
+
+    .. grid-item-card:: Overview
+
+        Learn about the Data Parallel Extension for NumPy*, its design
+        principles, and what it provides.
+
+        +++
+
+        .. button-ref:: overview
+            :ref-type: doc
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the overview
+
+    .. grid-item-card:: Quick Start Guide
+
+        Get started with installation, setup, and your first dpnp program.
+
+        +++
+
+        .. button-ref:: quick_start_guide
+            :ref-type: doc
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the quick start guide
+
+    .. grid-item-card:: API Reference
+
+        Detailed documentation of all supported NumPy functions and classes
+        in :py:mod:`dpnp`.
+
+        +++
+
+        .. button-ref:: dpnp_reference
+            :ref-type: ref
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            Access API Reference
+
+    .. grid-item-card:: Tensor (dpnp.tensor)
+
+        The underlying Array API-compliant implementation based on
+        data-parallel algorithms for accelerators.
+
+        +++
+
+        .. button-ref:: tensor
+            :ref-type: doc
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the tensor documentation
+
+    .. grid-item-card:: Development information
+
+        C++ backend API reference and extension documentation for developers.
+
+        +++
+
+        .. button-ref:: dpnp_backend_api
+            :ref-type: doc
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the backend API reference
+
+
 .. toctree::
    :maxdepth: 2
+   :hidden:
+   :caption: Contents:
 
    overview
    quick_start_guide
@@ -17,6 +102,7 @@ Data Parallel Extension for NumPy*
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
    :caption: Development information
 
    dpnp_backend_api

environments/base_build_docs.txt

@@ -1,3 +1,5 @@
 pyenchant==3.2.2
+sphinx-copybutton==0.5.2
+sphinx-design==0.6.1
 sphinxcontrib-googleanalytics==0.4
 sphinxcontrib-spelling==8.0.1

environments/building_docs.yml

@@ -5,6 +5,6 @@ dependencies:
   - python=3.13 # no dpctl package on PyPI with enabled python 3.14 support
   - cupy
   - sphinx
-  - sphinx_rtd_theme
+  - furo
   - pip:
     - -r base_build_docs.txt

pyproject.toml

@@ -86,8 +86,10 @@ coverage = [
 docs = [
   "Cython",
   "cupy",
+  "furo",
   "sphinx",
-  "sphinx_rtd_theme",
+  "sphinx-copybutton",
+  "sphinx-design",
   "pyenchant",
   "sphinxcontrib-googleanalytics",
   "sphinxcontrib-spelling"