Skip to content

DOC: Fix reference warning in some rst and code files. #24487

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
Sep 11, 2023
Merged

DOC: Fix reference warning in some rst and code files. #24487

merged 1 commit into from
Sep 11, 2023

Conversation

liang3zy22
Copy link
Contributor

Fix following reference warning:

arrays.dtypes.rst:303: WARNING: py:obj reference target not found: numpy.sctypeDict
routines.array-creation.rst:50: WARNING: py:mod reference target not found: numpy.core.records
routines.array-creation.rst:68: WARNING: py:mod reference target not found: numpy.core.defchararray
routines.ma.rst:36:<autosummary>:1: WARNING: py:class reference target not found: numpy.ma.core.MaskedArray
numpy/typing/__init__.py:docstring of numpy.typing:137: WARNING: py:obj reference target not found: numpy.rec
numpy/doc/source/release/1.16.0-notes.rst:58: WARNING: py:obj reference target not found: numpy.sctypeDict
numpy/doc/source/release/1.20.0-notes.rst:827: WARNING: py:obj reference target not found: numpy.rec.fromfile
numpy/doc/source/release/1.20.0-notes.rst:841: WARNING: py:obj reference target not found: numpy.distutils.fcompiler
numpy/doc/source/release/1.20.2-notes.rst:41: WARNING: py:obj reference target not found: dtype.__getitem__
numpy/doc/source/release/1.7.0-notes.rst:261: WARNING: py:obj reference target not found: formatter
numpy/doc/source/user/basics.indexing.rst:492: WARNING: py:const reference target not found: NaN

There are some reference warning about following:

routines.ma.rst:36:<autosummary>:1: WARNING: py:class reference target not found: numpy.ma.core.MaskedArray
maskedarray.generic.rst:106:<autosummary>:1: WARNING: py:class reference target not found: numpy.ma.core.MaskedArray

The warning is from docstree of masked_array, which is generated by sphinx.ext.autodoc extensions, something like following:

alias of py:class:`numpy.ma.core.MaskedArray`

But numpy.ma.core.MaskedArray is not a correct class reference, it is a path reference.
Is there a way to add docstring for alias?

rossbar
rossbar reviewed Aug 22, 2023
View reviewed changes
Copy link
Contributor

@rossbar rossbar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a few nits, overall definitely an improvement!

numpy/typing/__init__.py Outdated
@@ -135,7 +135,7 @@
Record array dtypes
~~~~~~~~~~~~~~~~~~~

The dtype of `numpy.recarray`, and the `numpy.rec` functions in general,
The dtype of `numpy.recarray`, and the `numpy.record` functions in general,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW I think this one intended to refer to the numpy.rec module, not the numpy.record scalar. I'd vote for:

Suggested change
The dtype of `numpy.recarray`, and the `numpy.record` functions in general,
The dtype of `numpy.recarray`, and the ``numpy.rec`` functions in general,

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will update it in next push.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used :ref:routines.array-creation.rec instead since all functions in this part are all functions of numpy.rec module. Just using numpy.rec may let users confused since there are no numpy.rec module section.

@liang3zy22 liang3zy22 force-pushed the somrefwarn branch 3 times, most recently from 1a444f2 to 2fef17b Compare August 28, 2023 10:08
mattip
mattip reviewed Aug 28, 2023
View reviewed changes
doc/source/reference/arrays.dtypes.rst Outdated
@@ -296,7 +296,7 @@ String with comma-separated fields
>>> dt = np.dtype("a3, 3u8, (3,4)a10")

Type strings
Any string in :obj:`numpy.sctypeDict`.keys():
Any string in ``numpy.sctypeDict.keys()``:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sctypeDict will be removed for NumPy2.0. Do we have a replacement?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a warning to tell users sctypeDict will be removed for NumPy2.0 now? Then we can update this part for replacement if we have got a good replacement.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rgommers, @seberg, @ngoldbaum: what is the canonical list of strings that can be used for dtypes in NumPy2.0, once numpy.sctypeDict disappears?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the list of canonical Python names for dtypes, see gh-24651. There should not be a new list of strings accessible in the API. The examples right below this line are already fine, so I recommend replace this line with "Any string name of a NumPy dtype, e.g.:"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the commit based on @rgommers suggestion.

@liang3zy22 liang3zy22 force-pushed the somrefwarn branch 3 times, most recently from 5b3b943 to 1dcc4dd Compare September 3, 2023 23:56
@mattip mattip merged commit cba1869 into numpy:main Sep 11, 2023
@mattip
Copy link
Member

mattip commented Sep 11, 2023

Thanks @liang3zy22

@liang3zy22 liang3zy22 deleted the somrefwarn branch September 11, 2023 06:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@rgommers rgommers rgommers left review comments

@mattip mattip mattip left review comments

@rossbar rossbar rossbar left review comments

Assignees
No one assigned
Labels
04 - Documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@liang3zy22 @mattip @rgommers @rossbar