diff --git a/CHANGELOG.md b/CHANGELOG.md index a9dc748fe34c..351411344bf1 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/doc/_static/dpnp-custom.css b/doc/_static/dpnp-custom.css new file mode 100644 index 000000000000..6c4495a213ba --- /dev/null +++ b/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; +} diff --git a/doc/_static/dpnp-custom.js b/doc/_static/dpnp-custom.js new file mode 100644 index 000000000000..b40ef0365036 --- /dev/null +++ b/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

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

tags, so multi-paragraph descriptions +// arrive as sibling

elements inside

  • . 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); +}); +}()); diff --git a/doc/conf.py b/doc/conf.py index 57119eab5396..0c31bc413caa 100644 --- a/doc/conf.py +++ b/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,7 +110,7 @@ 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 ------------------------------------------------- @@ -114,23 +118,20 @@ # 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 --------------------------------------------- diff --git a/doc/ext_links.txt b/doc/ext_links.txt index d7a858723fc6..f88c7f4c4069 100644 --- a/doc/ext_links.txt +++ b/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 diff --git a/doc/index.rst b/doc/index.rst index 847680fc11d9..4a21460162b1 100644 --- a/doc/index.rst +++ b/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 diff --git a/environments/base_build_docs.txt b/environments/base_build_docs.txt index edab09ee45ab..79e8cda1f45a 100644 --- a/environments/base_build_docs.txt +++ b/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 diff --git a/environments/building_docs.yml b/environments/building_docs.yml index 0857dd8431ba..07aeef7b68cd 100644 --- a/environments/building_docs.yml +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 6c70c222bb63..47c36f4acb8f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -86,8 +86,10 @@ coverage = [ docs = [ "Cython", "cupy", + "furo", "sphinx", - "sphinx_rtd_theme", + "sphinx-copybutton", + "sphinx-design", "pyenchant", "sphinxcontrib-googleanalytics", "sphinxcontrib-spelling"