Integrate dpnp.tensor docs to dpnp

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/_templates/autosummary/cython_class.rst

@@ -0,0 +1,29 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ name }}
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree: generated
+   {% for item in methods if item != "__init__" %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree: generated
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/_templates/autosummary/elementwise.rst

@@ -0,0 +1,12 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+{% if objtype == "data" %}
+.. auto{{ objtype }}:: {{ objname }}
+    :no-value:
+{% endif %}
+
+{% if objtype == "function" %}
+.. auto{{ objtype }}:: {{ objname }}
+{% endif %}

doc/_templates/autosummary/usm_ndarray.rst

@@ -0,0 +1,48 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+
+
+.. autoclass:: {{ name }}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree: generated
+      :nosignatures:
+   {% for item in methods if item != "__init__" %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree: generated
+      :nosignatures:
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   .. rubric:: {{ _('Special attributes') }}
+
+   .. autosummary::
+      :toctree: generated
+      :nosignatures:
+
+      ~{{name}}.__dlpack_device__
+      ~{{name}}.__dlpack__
+      ~{{name}}.__sycl_usm_array_interface__
+      ~{{name}}._pointer
+      ~{{name}}._element_offset
+      ~{{name}}._byte_bounds
+
+   {% endif %}
+   {% endblock %}

doc/conf.py

@@ -6,7 +6,6 @@
 # http://www.sphinx-doc.org/en/master/config
 
 from datetime import datetime
-from urllib.parse import urljoin
 
 from sphinx.ext.autodoc import FunctionDocumenter
 from sphinx.ext.napoleon import NumpyDocstring, docstring
@@ -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,23 @@
 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 = (
+    '<span style="font-size:2em;font-weight:700">dpnp</span><br>'
+    '<small style="font-size:0.75em">Data Parallel Extension for NumPy<br>'
+    + release
+    + " documentation</small>"
+)
+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 +136,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 +151,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 ---------------------------------------------
@@ -232,9 +234,6 @@ def _can_document_member(member, *args, **kwargs):
 
 autosummary_generate = True
 
-_DPCTL_021_BASE = "https://intelpython.github.io/dpctl/0.21.1/"
-_DPCTL_021_INV = urljoin(_DPCTL_021_BASE, "objects.inv")
-
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
@@ -306,65 +305,3 @@ def _parse_returns_section_patched(self, section: str) -> list[str]:
 
 
 NumpyDocstring._parse_returns_section = _parse_returns_section_patched
-
-
-# TODO: Remove once dpnp.tensor docs are generated in dpnp
-def _load_dpctl_tensor_inventory(app):
-    """Load dpctl 0.21.1 inventory for dpnp.tensor fallback only."""
-    from sphinx.ext.intersphinx import fetch_inventory
-    from sphinx.util import logging
-
-    logger = logging.getLogger(__name__)
-
-    try:
-        inv = fetch_inventory(app, _DPCTL_021_BASE, _DPCTL_021_INV)
-    except Exception as exc:
-        logger.warning(
-            "Failed to load dpctl 0.21.1 inventory from %s: %s",
-            _DPCTL_021_INV,
-            exc,
-        )
-        inv = {}
-
-    app.builder.env._dpctl_tensor_021_inventory = inv
-
-
-# TODO: Remove once dpnp.tensor docs are generated in dpnp
-def _resolve_dpnp_tensor_refs(app, env, node, contnode):
-    """Resolve dpnp.tensor.* references to dpctl 0.21.1 documentation.
-
-    This temporary workaround is needed because dpnp.tensor documentation
-    is not generated yet, while the corresponding API is still documented
-    in dpctl 0.21.1.
-    """
-    from docutils import nodes as docutils_nodes
-
-    target = node.get("reftarget", "")
-    if not target.startswith("dpnp.tensor"):
-        return None
-
-    dpctl_target = target.replace("dpnp.tensor", "dpctl.tensor", 1)
-    dpctl_tensor_inv = getattr(env, "_dpctl_tensor_021_inventory", {})
-
-    for _objtype, objects in dpctl_tensor_inv.items():
-        if dpctl_target not in objects:
-            continue
-
-        item = objects[dpctl_target]
-        location = item.uri
-        if location.endswith("$"):
-            location = location[:-1] + dpctl_target
-
-        refuri = urljoin(_DPCTL_021_BASE, location)
-        newnode = docutils_nodes.reference(
-            "", "", internal=False, refuri=refuri
-        )
-        newnode += contnode.deepcopy()
-        return newnode
-
-    return None
-
-
-def setup(app):
-    app.connect("builder-inited", _load_dpctl_tensor_inventory, priority=400)
-    app.connect("missing-reference", _resolve_dpnp_tensor_refs, priority=400)