diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a2dc01b8987..d34a10844bc1 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..b39972f6df3e --- /dev/null +++ b/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; +} diff --git a/doc/_static/dpnp-custom.js b/doc/_static/dpnp-custom.js new file mode 100644 index 000000000000..cce448d9c17b --- /dev/null +++ b/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 ? "
" : "") + extra.join("
"); + + firstP.innerHTML = + before + '
' + after + ""; +} + +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..91a2e9a2d419 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,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,7 +109,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,12 +117,10 @@ # 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 --------------------------------------------- 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"