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,91 @@
+/* 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 tbody tr.row-odd,
+body table.docutils tbody tr.row-even {
+    background: transparent !important;
+}
+
+body table.docutils td,
+body table.docutils th {
+    border: 1px solid var(--color-foreground-border) !important;
+    padding: 8px 12px;
+}
+
+body table.docutils thead th {
+    background-color: #e8edf2 !important;
+}
+
+body table.docutils tbody tr.row-odd {
+    background-color: #f5f5f5 !important;
+}
+
+/* Docstring section titles: normal case, bold, gray 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: #f5f5f5;
+    padding: 4px 8px;
+}
+
+/* Constants page: lighter section headers */
+#constants dd p.rubric {
+    background-color: transparent;
+    padding: 0;
+    border-bottom: 1px solid #ccc;
+}
+
+/* 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 on new line (via custom.js) */
+dl.field-list dd .param-desc {
+    display: inline-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;
+}
+
+/* Dark mode */
+@media (prefers-color-scheme: dark) {
+    body table.docutils thead th {
+        background-color: #2a2e33 !important;
+    }
+    body table.docutils tbody tr.row-odd {
+        background-color: #1e2227 !important;
+    }
+}
+
+body[data-theme="dark"] table.docutils thead th {
+    background-color: #2a2e33 !important;
+}
+body[data-theme="dark"] table.docutils tbody tr.row-odd {
+    background-color: #1e2227 !important;
+}

doc/_static/dpnp-custom.js

@@ -0,0 +1,42 @@
+(function() {
+var separator = " – ";
+var separatorAlt = " -- ";
+
+function reformatEntry(container)
+{
+    var paragraphs = container.querySelectorAll(":scope > p");
+    if (!paragraphs.length)
+        return;
+
+    var firstP = paragraphs[0];
+    var idx = firstP.innerHTML.indexOf(separator);
+    var sep = separator;
+    if (idx === -1) {
+        idx = firstP.innerHTML.indexOf(separatorAlt);
+        sep = separatorAlt;
+    }
+    if (idx === -1)
+        return;
+
+    var before = firstP.innerHTML.substring(0, idx);
+    var after = firstP.innerHTML.substring(idx + sep.length);
+
+    var extra = [];
+    for (var i = 1; i < paragraphs.length; i++) {
+        extra.push(paragraphs[i].innerHTML);
+        paragraphs[i].remove();
+    }
+    if (extra.length)
+        after += (after ? "<br>" : "") + extra.join("<br>");
+
+    firstP.innerHTML =
+        before + '<br><span class="param-desc">' + after + "</span>";
+}
+
+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,14 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx_copybutton",
+    "sphinx_design",
     "sphinxcontrib.googleanalytics",
     "sphinxcontrib.spelling",
 ]
 
+copybutton_prompt_text = ">>> "
+
 googleanalytics_id = "G-554F8VNE28"
 googleanalytics_enabled = True
 
@@ -106,20 +109,18 @@
 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,
-}
+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 = {}
 
 # 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
@@ -130,7 +131,12 @@
 # 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 +146,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"