DOC: add docstrings for numeric types - #11858

Test failure is bogus.

AFAIR, setting __doc__ on the types through add_newdocs doesn't actually work - but perhaps I'm mistaken.

I think we need to tread carefully here - we might end up wanting different online docs to the local docs - local docs know the exact mapping of sized aliases to C types, whereas the sphinx docs shouldn't make assumptions about the user's machine.

we might end up wanting different online docs to the local docs - local docs know the exact mapping of sized aliases to C types, whereas the sphinx docs shouldn't make assumptions about the user's machine.

OK, this is an important point for good documentation. I will take a second stab, keeping this in mind.

To get a better picture: are these docstrings meant to also replace the list of scalar dtypes in the docs on the long run (i.e., with autosummary generated documentation) ? What level of detail is needed, and in what context should these docstrings present in the online documentation?

Perhaps the correct path for now is:

• Document the native unsized np.int_ types using add_new_docs, with something like

  Corresponds to the C long type

• Add a generated sentence like

  On this platform, this type is aliased to np.int64 <docs for int64>

I'm not completely happy with how this sketch of a solution looks, but it should be a step closer to the actual correct, yet platform-flexible documentation. Is this where this PR wants to go?

I like the direction this is going in - I think it will definitely be an improvement over what already exists.

I think we'll need to think a little more about how to use this with server-built sphinx builds - but for local users using help(type), I think this does exactly the right thing.

Right now none of these docstrings are in sphinx anyway, so we can punt that to a later PR.

Update: fixed minor things, but:

• clongfloat is mentioned in the existing documentation, instead of clongdouble.
• The reference documentation on intp mentions ssize_t instead of intptr_t.

But these can probably be fixed once these docstrings get included in the reference documentation?

Next, stackoverflow shows a few hackish way of detecting sphinx (https://stackoverflow.com/questions/20843737/check-if-sphinx-doc-called-the-script), but something feels wrong about actually accessing and using this when generating the docs?

Lets leave worrying about sphinx to a later PR.

Both your points are correct - but I think the other docs are just subtly wrong, and I would prefer to aim for correctness not consistency - your most recent update looks good

Can you include both the name and doc in the list of aliases? Right now I think you only add the doc.

Yes, forgot that, thanks!

Also, adding float_ and complex_ to the list of aliases would be handy

Since these seem to be 'hardcoded' aliases, I'm adding these as part of the docstring itself, and not with this alias list construct.

I'm adding these as part of the docstring itself

Fine by me.

Can you show the output of help(np.intc), help(np.long), and help(np.longlong) after this change?

>>> print(np.intc.__doc__)
Signed integer type, compatible with C ``int``.
    Character code: ``'i'``.
>>> print(np.long.__doc__)
int(x=0) -> integer
int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments
are given.  If x is a number, return x.__int__().  For floating point
numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string,
bytes, or bytearray instance representing an integer literal in the
given base.  The literal can be preceded by '+' or '-' and be surrounded
by whitespace.  The base defaults to 10.  Valid bases are 0 and 2-36.
Base 0 means to interpret the base from the string as an integer literal.
>>> int('0b100', base=0)
4
>>> print(np.longlong.__doc__)
Signed integer type, compatible with C ``long long``. 
    Character code: ``'q'``.

I'll have a closer look at that other PR later.

I'd specifically like to see the output of help. Also I made a typo, and said np.long not np.int_.

I'd specifically like to see the output of help.

Sorry, here you go:

help(np.intc)

Help on class int32 in module numpy:

class int32(signedinteger)
 |  Signed integer type, compatible with C ``int``.
 |  Character code: ``'i'``.
 |  
 |  Method resolution order:
 |      int32
 |      signedinteger
 |      integer
 |      number
 |      generic
 |      builtins.object
 |  
 |  Methods defined here:
 |  
 |  __abs__(self, /)
 |      abs(self)
 |  
 |  __add__(self, value, /)
 |      Return self+value.
 |  
 |  __and__(self, value, /)
 |      Return self&value.
[...]
 |  astype(...)
 |      Not implemented (virtual attribute)
 |      
 |      Class generic exists solely to derive numpy scalars from, and possesses,
 |      albeit unimplemented, all the attributes of the ndarray class
 |      so as to provide a uniform API.
 |      
 |      See Also
 |      --------
 |      The corresponding attribute of the derived class of interest.
 |  
[...]

`help(np.int_)

Help on class int64 in module numpy:

class int64(signedinteger)
 |  Signed integer type, compatible with Python `int` anc C ``long``.
 |  Character code: ``'l'``.
 |  
 |  Method resolution order:
 |      int64
 |      signedinteger
 |      integer
 |      number
 |      generic
 |      builtins.object
[...]

help(np.longlong)

Help on class int64 in module numpy:

class int64(signedinteger)
 |  Signed integer type, compatible with C ``long long``. 
 |  Character code: ``'q'``.
 |  
 |  Method resolution order:
 |      int64
 |      signedinteger
 |      integer
 |      number
 |      generic
 |      builtins.object
[...]

Made the changes I suggested below myself. Feel free to tweak if you want, but I think this is ready to go in

I've still implemented the one small change in numeric_type_aliases you suggested.

Oh, and almost forgot, but I yesterday noticed that this actually doesn't work for the complex types. These types already have a docstring set in the C code, and add_newdocs will not overwrite the existing one (but does so silently):

>>> help(np.cdouble)
Help on class complex128 in module numpy:

class complex128(complexfloating, builtins.complex)
 |  Composed of two 64 bit floats

I guess I've missed this since been focusing on the signed and unsigned integers, since they had these C type equivalence issues.

The line with this docstring is here: https://github.com/numpy/numpy/blob/master/numpy/core/src/multiarray/scalartypes.c.src#L3773. My instinctive reaction would be to make this consistent and remove the docstring from the C code, but then I don't know the reason why these docstrings are there?

My instinctive reaction would be to make this consistent and remove the docstring from the C code

Seems sensible to me. Even if there is a reason for them to be there, it would apply to all of the docstrings anyway, not just that one,

Almost done! :-)

Running the code from #10106 again, there are a few more undocumented numeric types that seem to be related, part of the type hierarchy of scalar types:

• <class 'numpy.complexfloating'> (np.complexfloating)
• <class 'numpy.flexible'> (np.flexible)
• <class 'numpy.floating'> (np.floating)
• <class 'numpy.inexact'> (np.inexact)
• <class 'numpy.integer'> (np.integer)
• <class 'numpy.number'> (np.number)
• <class 'numpy.signedinteger'> (np.signedinteger)
• <class 'numpy.unsignedinteger'> (np.unsignedinteger)

Futhermore, numpy.void seems like it could still be a couple of lines included in this PR as well, just after object ?

Perhaps let this go in as-is, and add the rest in another PR?

I'm with @mattip on this one - documenting the abstract types seems like a separate task to documenting the concrete ones.

Just tweaked the release notes - I plan to squash and merge in a day or two, in case anyone else decides to weigh in.

Thanks @YannickJadoul. And thanks to Eric for helping get this knocked into shape.

Thanks indeed, @eric-wieser, for the guidance and remarks!