DOC: fix nitpicky Sphinx warnings in NEP 13#31377
Conversation
…eferences with inline literals
|
|
||
| Subclasses can be easily constructed if methods consistently use | ||
| :func:`super` to pass through the class hierarchy [7]_. To support | ||
| :func:``super`` to pass through the class hierarchy [7]_. To support |
There was a problem hiding this comment.
These should work. They uses the intersphinx protocol to link to the python documentation. It would be better to find out why :func: is not working than to reformat all these to code.
There was a problem hiding this comment.
Thanks for the suggestion!
I restored :func: roles where intersphinx resolves correctly.
For cases like numpy.matmul that do not resolve, I used inline
literals to avoid broken references. The NEP now builds cleanly without introducing new warnings.
| ====== ============ ========================================= | ||
| Symbol Operator NumPy Ufunc(s) | ||
| ====== ============ ========================================= | ||
| ``<`` ``lt`` :func:`less` |
There was a problem hiding this comment.
These should render properly. I wonder what is off. Maybe you need something like this neare the top of the file?
.. currentmodule:: numpy
There was a problem hiding this comment.
The file already includes .. currentmodule:: numpy at the top, so
:func: roles should resolve via intersphinx. However, in this section
(particularly inside the table), references like :func:less`` were not
resolving and were causing nitpicky (-n -W) build failures.
To verify, I tested:
- Keeping
:func:→ still produced unresolved reference warnings - Adding
.. currentmodule:: numpyagain → no change - Using fully-qualified
:func:numpy.less`` → works, but is more verbose - Using inline literals (
less) → removes warnings and keeps the table readable
Given that, I switched the problematic entries to inline literals to
avoid broken references while keeping the content unchanged.
Could you clarify what specific rendering or linking you’d prefer here?
I’m happy to adjust
if this si the expected style i could switch to fully-qualified :func:~numpy.less``
There was a problem hiding this comment.
It would be nice to see the links work, I think. So if the last works lets go with that
There was a problem hiding this comment.
hey @mattip I updated all ufunc references to fully-qualified links (e.g. :func:~numpy.matmul),
and verified that they now resolve correctly without reference warnings.
The remaining warnings appear to be unrelated to this file (toctree / NEP indexing).
Please let me know if you'd like me to adjust anything further.
|
There are still lots of warnings. Try to build the docs locally: |
he @mattip i re-ran the NEP docs build in my local setup after the latest changes. The unresolved NEP 13 cross-reference warnings related to the NumPy function links ( The remaining warnings are existing repository-wide NEP warnings such as:
These are not coming from the NEP 13 changes themselves and still appear when building the full NEP docs locally. still to be sure as told by i set up a fresh virtual environment, installed both requirements/doc_requirements.txt and requirements/build_requirements.txt, initialized the submodules, and rebuilt the docs locally using: python -m sphinx -n -W -b html . _build/html Since the original issue scope was fixing the NEP 13 rendering/reference issues, could you confirm whether this is now in the expected state, or whether you’d also like me to work on the broader NEP toctree warnings separately |
PR summary
Fix unresolved Sphinx references in NEP 13.
This PR replaces
:func:roles that cannot be resolved in the NEPdocumentation build with inline literals (
func), preventing warningswhen building NEPs with nitpicky mode (-n -W).
This reduces warnings in NEP 13 without changing content or meaning.
Remaining warnings in the NEP build are related to toctree structure and
are outside the scope of this PR.
First time committer introduction
Hi, I’m a first-time contributor to NumPy.
I’m a computer science student and have been using NumPy in my academic work and projects. While exploring the repository and documentation, I wanted to contribute by improving documentation quality.
This issue stood out as a good opportunity to understand the documentation build system and Sphinx behavior, so I worked on fixing the unresolved references in NEP 13.
AI Disclosure
AI was only used for guidance in understanding Sphinx warnings and debugging reference resolution issues.
The final code changes (replacement of unresolved
:func:roles with inline literals) were reviewed and applied manually, and no AI-generated code was directly used. .