Skip to content

Use numpydoc to render the API reference - #3059

Open
vlad-perevezentsev wants to merge 7 commits into
masterfrom
use_numpydocs_in_docs_build
Open

Use numpydoc to render the API reference#3059
vlad-perevezentsev wants to merge 7 commits into
masterfrom
use_numpydocs_in_docs_build

Conversation

@vlad-perevezentsev

Copy link
Copy Markdown
Contributor

This PR switches the documentation build from sphinx.ext.napoleon to numpydoc to render the API reference.
numpydoc renders the Parameters and Returns sections as definition lists out of the box, which lets us remove:

  • the custom doc/_static/dpnp-custom.js that reformatted parameter
    descriptions, together with the CSS rules that only supported it;
  • the napoleon monkeypatch for namedtuple Returns (numpydoc handles it
    natively).

A small hook keeps the dpnp-specific Limitations section and a some docstrings are adjusted for numpydoc's stricter parser.

  • Have you provided a meaningful PR description?
  • Have you added a test, reproducer or referred to an issue with a reproducer?
  • Have you tested your changes locally for CPU and GPU devices?
  • Have you made sure that new changes do not introduce compiler warnings?
  • Have you checked performance impact of proposed changes?
  • Have you added documentation for your changes, if necessary?
  • Have you added your changes to the changelog?

@github-actions

github-actions Bot commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

View rendered docs @ https://intelpython.github.io/dpnp/pull/3059/index.html

@github-actions

github-actions Bot commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Array API standard conformance tests for dpnp=0.21.0dev8=py314ha0e2e8e_9 ran successfully.
Passed: 1376
Failed: 0
Skipped: 6

@coveralls

coveralls commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Coverage Status

coverage: 78.494%. remained the same — use_numpydocs_in_docs_build into master

@antonwolfy antonwolfy added this to the 0.21.0 release milestone Sep 8, 2026
@antonwolfy

Copy link
Copy Markdown
Contributor

Small rendering mismatch vs the legacy build worth a fix: parameter/return types now render upright + semibold instead of italic.

Cause is purely CSS. numpydoc emits the type as <span class="classifier">, and the italic comes from Sphinxs built-in basic.css (.classifier { font-style: oblique }). NumPys pydata-sphinx-theme @imports basic.css so types are italic, and napoleon previously wrapped the type in <em>. Furo neither imports basic.css nor styles .classifier, and it makes the whole <dt> term semibold, so the type ends up bold/upright.

Proposed fix, add to doc/_static/dpnp-custom.css:

/* numpydoc param/return types: italic like NumPy, not bold */
.classifier {
    font-style: italic;
    font-weight: 400;
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants