Repository navigation
DOC: Add missing documentation for top-level functions #10106
Description
Exposed are:
-
<function <lambda> at 0x0000026322836C80>(np.deprecate_with_doc) -
<class 'numpy._import_tools.PackageLoader'>(np.PackageLoader) -
<class 'numpy.core._internal.TooHardError'>(np.TooHardError) - DOC: adding docstring to TooHardError class #21471 -
<function _numpy_tester at 0x000002632285C268>(np._numpy_tester) -
<built-in function compare_chararrays>(np.compare_chararrays) - DOC: add a docstring for the function 'compare_chararrays' (See #10106) #12338 -
<built-in function datetime_as_string>(np.datetime_as_string) - DOC: Add documentation for datetime_as_string #10107 -
<built-in function datetime_data>(np.datetime_data) - DOC: Add documentation for datetime_data #10108 -
<built-in function int_asbuffer>(np.int_asbuffer) - Remove int_asbuffer #12425 -
<built-in function nested_iters>(np.nested_iters) - DOC: nditer.nested_iters are not documented #10009 -
<function show at 0x00000263225800D0>(np.show_config) -show_config()has no docstring and is not in the online docs. #9258 -
<class 'numpy.bytes_'>(np.bytes0,np.string_,np.bytes_) -
<class 'numpy.character'>(np.character) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.complexfloating'>(np.complexfloating) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.datetime64'>(np.datetime64) - datetime64("now") is undocumented #10003, datetime64 not present in intersphinx inventory #10039, ... -
<class 'numpy.flexible'>(np.flexible) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.float16'>(np.half,np.float16) - DOC: add docstrings for numeric types #11858 -
<class 'numpy.float64'>(np.longdouble,np.longfloat) - DOC: add docstrings for numeric types #11858 -
<class 'numpy.floating'>(np.floating) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.inexact'>(np.inexact) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.int32'>(np.intc) - DOC: add docstrings for numeric types #11858 -
<class 'numpy.integer'>(np.integer) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.number'>(np.number) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.signedinteger'>(np.signedinteger) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.str_'>(np.str0,np.unicode_,np.str_) -
<class 'numpy.timedelta64'>(np.timedelta64) -
<class 'numpy.uint16'>(np.uint16,np.ushort) - DOC: add docstrings for numeric types #11858 -
<class 'numpy.uint32'>(np.uintc) - DOC: add docstrings for numeric types #11858 -
<class 'numpy.uint32'>(np.uint,np.uint32) - DOC: add docstrings for numeric types #11858 -
<class 'numpy.uint64'>(np.uint64,np.uintp,np.ulonglong,np.uint0) - DOC: add docstrings for numeric types #11858 -
<class 'numpy.uint8'>(np.uint8,np.ubyte) - DOC: add docstrings for numeric types #11858 -
<class 'numpy.unsignedinteger'>(np.unsignedinteger) - DOC: Add docstrings for abstract types in scalar type hierarchy #12027 -
<class 'numpy.void'>(np.void0,np.void)
Steps to document many of these:
- Find the long-form of the name, such as
np.core.multiarray.uint16 - Add the documentation
toin the appropriate placenumpy/add_newdocs.py - Find an appropriate place to link to the function within
:/doc/source/reference/routines.*.rst- look at existing files to see how
Script to generate the above
from collections.abc import Callable
ndoc = set(
v
for k, v in vars(np).items()
if isinstance(v, Callable) and v.__doc__ is None
)
ndoc = sorted(
ndoc,
key=lambda v: (isinstance(v, type) and issubclass(v, np .generic), v.__qualname__)
)
print('\n'.join(
'* [ ] `{!r}` ({})'.format(
v,
', '.join('`np.{}`'.format(k) for k, v2 in vars(np).items() if v2 is v)
)
for v in ndoc
))
Activity
mohdsanadzakirizvi commentedon Dec 24, 2017
I would like to work on this as my first contribution, is it open? :)
mattip commentedon May 23, 2018
It seems the basic classes are documented, no?
eric-wieser commentedon May 24, 2018
np.float16.__doc__ is Noneon my machine. Are you testing with PyPy? I think this might be another case of things happening afterPyType_Ready.DOC: add docstring for np.float16 (see numpy#10106)
DOC: add docstrings for uint8, uint16, uint32, uint64 (see numpy#10106)
DOC: add docstring for np.float16 (see numpy#10106)
DOC: add docstrings for numeric types (#11858)
eric-wieser commentedon Sep 19, 2018
Thanks @YannickJadoul for knocking out a whole bunch of these!
Merge pull request #12338 from ryzheboka/docs-for-compare_chararrays
smellslikekeenspirit commentedon Mar 24, 2019
Hi, can I work on the documentation for the unticked functions? Or have they been done already?
5 remaining items
rgommers commentedon Dec 10, 2019
Hmm, that PR looks a little complicated. @engineerlisa please have a look if that PR makes sense to you (
@ghostis someone who disappeared from GitHub); the weird formatting stuff in the PR is because the docstring goes through some machinery that generates the__config__.pyfile so simply""" ... """content won't work.@eric-wieser I removed the "good first issue" label, the left overs aren't a matter of writing docs anymore. I think a maintainer should finish the last bits here.
engineerlisa commentedon Dec 14, 2019
Thank you for getting back to me. I understand some parts of that PR. Based on your removing the tag, I'm going to find another candidate for my first contribution.
eric-wieser commentedon Oct 12, 2020
Just two left here
np.deprecate_with_doc, which could do with a docstring similar tonp.deprecatenp.TooHardError, which I think is raised only by https://numpy.org/doc/stable/reference/generated/numpy.shares_memory.htmlBoth of these should be easy to document, so I'm going to add back the "good first issue" label
kumudlakara commentedon Nov 23, 2020
Hey, I'm a first time contributor and I would like to take up the remaining two functions if they are still open. Any guidance would be appreciated. Thanks!
mattip commentedon Nov 23, 2020
Hi @kumudlakara. You should start with the contributor guide for an overview, especially the section on documentation and then the development workflow for the details. We don't assign issues, so be sure to mark your PR with
xref gh-10106to get a cross-reference to show up here, that way people will know you are working on it.kumudlakara commentedon Nov 24, 2020
Alright, Thank you @mattip .
Radhika14soni commentedon Dec 16, 2020
Hi, I'm a first time contributor and I would like to work on this issue if they are still open. Any guidance would be appreciated. Thanks!
mattip commentedon Dec 17, 2020
Hi @Radhika14soni and welcome. I commented above on how to get familiar with the process. Since
deprecate_with_docis underway, the only remaining function lacking documentation isnp.TooHardError. It is raised only by https://numpy.org/doc/stable/reference/generated/numpy.shares_memory.html, which should give you a hint as to the needed docstring.Radhika14soni commentedon Dec 17, 2020
@mattip Hello I'd like to work on it. Am I supposed to make changes in _add_newdocs.py?
mattip commentedon Dec 17, 2020
Since this is a pure-python class, the change would be to add a docstring to the class definition like for the other exception classes in that file.
mugunthanramesh commentedon Feb 24, 2021
Is there any works pending on this issue that I can take ? I am new to numpy contribution and looking for anything to work on
melissawm commentedon Feb 24, 2021
From the comments above it looks like this issue is taken care of, @mugunthanramesh . But feel free to browse other Documentation-related issues and ping me if you need help getting started. Cheers!
mattip commentedon Feb 24, 2021
Closing then. Please open a new issue if there are still missing docstrings, this one is too difficult to navigate.