diff --git a/doc/_static/dpnp-custom.css b/doc/_static/dpnp-custom.css new file mode 100644 index 00000000000..b39972f6df3 --- /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 00000000000..cce448d9c17 --- /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 57119eab539..107edb8956c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -68,10 +68,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 +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,12 +118,15 @@ # 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 = ( + 'dpnp
' + 'Data Parallel Extension for NumPy
' + + 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 +137,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 +152,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/index.rst b/doc/index.rst index 847680fc11d..20d0f3ee14d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,22 +1,87 @@ .. _index: .. include:: ./ext_links.txt +=================================== Data Parallel Extension for NumPy* -================================== +=================================== .. module:: dpnp :no-index: +Python package :py:mod:`dpnp` implements a subset of `NumPy*`_ that can be +executed on any data parallel device. The subset is a drop-in replacement of +core `NumPy*`_ functions and numerical data types. + +.. 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 + + .. toctree:: :maxdepth: 2 + :hidden: + :caption: Contents: overview quick_start_guide reference/index tensor - -.. toctree:: - :maxdepth: 1 - :caption: Development information - dpnp_backend_api diff --git a/environments/base_build_docs.txt b/environments/base_build_docs.txt index edab09ee45a..79e8cda1f45 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 0857dd8431b..07aeef7b68c 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 773d3cb4590..d7230c40159 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"