8000 DOC: Examples in docstrings – tracking issue · Issue #21351 · numpy/numpy · GitHub
[go: up one dir, main page]
Skip to content

DOC: Examples in docstrings – tracking issue #21351

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
Closed
InessaPawson opened this issue Apr 17, 2022 · 29 comments · Fixed by #27598
Closed

DOC: Examples in docstrings – tracking issue #21351

InessaPawson opened this issue Apr 17, 2022 · 29 comments · Fixed by #27598
Labels
04 - Documentation sprintable Issue fits the time-frame and setting of a sprint

Comments

@InessaPawson
Copy link
Member
InessaPawson commented Apr 17, 2022 •
edited
Loading

"Examples, more examples, and more detailed examples" is the recurrent theme in the feedback about the NumPy documentation we received via the 2020 and 2021 NumPy user surveys.

If you come across a docstring where a function is missing an example or more/better examples are needed, please add a comment below.

Re: the “sprintable” label This could be a good activity for a sprint with new contributors as most of them are NumPy users. However, one doesn’t have to be a sprint participant to contribute to this initiative.
@youssefkhalil320
Copy link

how can I help in this issue ?

@mattip
Copy link
Member
mattip commented Apr 17, 2022

Take a look at the functions you use from NumPy, and see if the docstrings have examples similar to your non-trivial use cases. If not, comment below asking if it seems an example would help newer users figure out how to replicate what you do.

@InessaPawson
Copy link
Member Author

This could be a good activity for a sprint with new contributors as most of them are NumPy users. I’ll add the “sprint” label to the issue. However, one doesn’t have to be a sprint participant to contribute to this initiative.

@InessaPawson InessaPawson added the sprintable Issue fits the time-frame and setting of a sprint label Apr 17, 2022
@mar-galho
Copy link

Hi everyone!

One thing that could also be tracked is whether the existing examples in docstrings are following the standards listed in the documentation. I've found an example in fromnumeric.py (lines 171-189) that I'm not entirely sure that are in accordance to the documentation.

I'm willing to help on that.

@bhavukkalra
Copy link
Contributor

Hi, Just wanted to confirm. If the general DOCS (examples for various functions) are in the scope of this Issue or we are currently tracking only the DOC Strings.
I do see a lot of additions that can be done to the numpy.random.generated page
Link under discussion

@mar-galho
Copy link

I was talking to @InessaPawson about that. I do believe that this issue could be, in fact, split into several different ones. Even the docstrings, this could be split in tracking down the ones that are there, the ones that are not, the ones that follow the standards, et cetera.

@dbrs01
Copy link
dbrs01 commented May 5, 2022 •
edited by seberg
Loading

We can use some examples in polynomial.py. What do you think about the following two (one for polymulx, the other for polyval2d):

import numpy as np
from numpy.polynomial import polynomial as P

c=(-2, 0, 1)
P.polymulx(c)
#array([-0., -2.,  0.,  1.])


from numpy.polynomial.polynomial import polyval2d
a=polyval2d(2, -3j,  [(-1j,1.5,2), (1,0.2j,0)])  #This is -1jx⁰y⁰ + 1.5x⁰y¹ + 2x⁰y² + 1x¹y⁰ + 0.2jx¹y¹ + 0x¹y², evaluated at x = 2 and y=-3j
#(-14.799999999999997-5.5j)

@InessaPawson
Copy link
Member Author

Just wanted to confirm. If the general DOCS (examples for various functions) are in the scope of this Issue or we are currently tracking only the DOC Strings.

@bhavukkalra This issue is only for examples in docstrings. Please file a separate issue for examples in other parts of the NumPy documentation.
8000

@bhavukkalra bhavukkalra mentioned this issue May 6, 2022
Open
@melissawm
Copy link
Member

@dbrs01 this looks good - Would you like to submit a PR?

@dbrs01
Copy link
dbrs01 commented May 15, 2022 via email

@mar-galho
Copy link

I can help with the PRs if you feel this is something that could help. Feel free to post the examples here and I can submit the PRs.

@WarrenWeckesser
Copy link
Member
WarrenWeckesser commented Jun 29, 2022 •
edited
Loading

Some time ago I wrote a script to find SciPy functions whose docstrings are missing the "Examples" section; there is a copy of that script in scipy/scipy#7168. (Edit: the script for SciPy, find_functions_missing_examples.py is now maintained in my analyze-scipy-code repository on github.)

I just created a gist with a variation of that script that has been modified for NumPy: https://gist.github.com/WarrenWeckesser/c33d0236279cc5d73843f0497e14ed0e. (There is a lot that could be done with such a script; hack away on your own copy if you feel inspired.)

Here's the output when I run that script with the development version (main branch) of NumPy. Note that some of these functions have very short docstrings that say something like "See $SOMEOTHERFUNC for details." This is probably intentional, and these are not good candidates for new contributors or for use in a sprint. Also, it looks like some of these might be "namespace pollution": names from the main numpy namespace that also ended up in a submodule. When in doubt, ask the NumPy devs to confirm that a function should get an "Examples" section before you spend time working on it.

NumPy version 1.24.0.dev0+427.gf9bed20bf

np (22)
    add_docstring
    add_newdoc
    add_newdoc_ufunc
    alltrue
    copyto
    cumproduct
    deprecate_with_doc
    diag_indices_from
    fastCopyAndTranspose
    get_array_wrap
    get_include
    get_printoptions
    getbufsize
    msort
    product
    recfromcsv
    recfromtxt
    round_
    setbufsize
    sometrue
    tril_indices_from
    triu_indices_from
np.char (40)
    add
    array
    asarray
    center
    encode
    equal
    expandtabs
    find
    greater
    greater_equal
    index
    isalnum
    isalpha
    isdecimal
    isdigit
    islower
    isnumeric
    isspace
    istitle
    isupper
    join
    less
    less_equal
    ljust
    mod
    multiply
    not_equal
    partition
    replace
    rfind
    rindex
    rjust
    rpartition
    rsplit
    split
    splitlines
    startswith
    str_len
    translate
    zfill
np.ctypeslib (4)
    as_array
    as_ctypes
    as_ctypes_type
    load_library
np.ma (26)
    compress_cols
    compress_nd
    compress_rows
    compressed
    convolve
    correlate
    cov
    diag
    ediff1d
    in1d
    isin
    left_shift
    max
    min
    power
    put
    putmask
    reshape
    right_shift
    round
    round_
    setxor1d
    sort
    take
    union1d
    unique
np.random.Generator (2)
    beta
    exponential

Found 94 functions

@rossbar
Copy link
Contributor
rossbar commented Jun 30, 2022

FWIW this check is also now built-in to the numpydoc docstring validator, which can be run during a doc build. For example, when building the docs locally you can add numpydoc_validation_checks = {"EX01"} to conf.py to automatically report this info during the sphinx-build process.

@InessaPawson
Copy link
10000 Member Author

@WarrenWeckesser Thank you so much for sharing this information! I’ll file a separate issue for each function after consulting with our core developers.

@rossbar rossbar mentioned this issue Oct 31, 2022
Merged
@navyagarwal navyagarwal mentioned this issue Sep 22, 2023
Closed
This was referenced Dec 8, 2023
Closed
Closed
Merged
This was referenced Dec 17, 2023
Merged
Merged
@bmwoodruff bmwoodruff mentioned this issue May 16, 2024
Closed
@mattip
Copy link
Member
mattip commented May 21, 2024

We should rerun the script

@bmwoodruff
Copy link
Member
bmwoodruff commented May 22, 2024 •
edited
Loading

The old script was missing some functions, which I think is because of the issues related to _ArrayFunctionDispatcher from last year. For example #23032 and #23307.

I added the following lines to the script. EDIT: Found better way, using inspect.isroutine.

import inspect

Then I replaced funcs with

    funcs = [item for item in objects
             if inspect.isroutine(item[1])]

Here is the new list:

np (12)
    amax
    amin
    around
    getbufsize
    matrix_transpose
    setbufsize
    show_config
    show_runtime
    unique_all
    unique_counts
    unique_inverse
    unique_values
np.char (7)
    array
    isalpha
    isspace
    mod
    rfind
    splitlines
    startswith
np.ctypeslib (4)
    as_array
    as_ctypes
    as_ctypes_type
    load_library
np.lib (2)
    add_docstring
    add_newdoc
np.linalg (10)
    cross
    diagonal
    matmul
    matrix_norm
    matrix_transpose
    outer
    svdvals
    trace
    vecdot
    vector_norm
np.ma (6)
    convolve
    correlate
    left_shift
    put
    reshape
    take
np.rec (1)
    find_duplicate

Found 42 functions

Prior to the change, there were only 24. I noticed the script was missing svdvals, which is why I started working on it. My hope is to have the POSSEE team fill in all of these (that need it) by next week.

Unfortunately, the type <class 'numpy._ArrayFunctionDispatcher'> also captures a few classes that don't need examples. I spent a couple hours reading about the issues last year and changes made related to _ArrayFunctionDispatcher. Maybe someone has an idea of a more elegant fix to the script than what I provided above. Found a better way.

I tried adding numpydoc_validation_checks = {"EX01"} to conf.py, but was unable to see where/how this generated the needed report. I'd love advice on that.

@rossbar
Copy link
Contributor
rossbar commented May 22, 2024

I tried adding numpydoc_validation_checks = {"EX01"} to conf.py, but was unable to see where/how this generated the needed report. I'd love advice on that.

When you add numpydoc_validation_checks = {"EX01"} to conf.py the validation warnings appear in the sphinx build log. To capture the build log in a file, you can do something like:

make html 2>&1 | tee buildlog.txt

If you want to filter the log so that only the warnings associated with the validation checks are stored, try:

make html 2>&1 | tee >(grep -B1 -A1 "EX01" >> buildlog.txt )

@bmwoodruff
Copy link
Member

I'll share the output as a file buildlog.log, rather than copy/paste the output here. There are 1808 items.

@bmwoodruff
Copy link
Member

I modified the script above to use inspect.isroutine The results are slightly different than capturing numpy._ArrayFunctionDispatcher and then using isinstance. Here I the updated scripts, along with the output in a Jupyter notebook.

While working on this, I noticed that there were several functions on this list that had docstrings that were not published on the web version of the docs. This script uses the object.inv file from a doc build and compares each routine against that list. I'll be including a PR in a bit with the missing ma links (they don't show on the attached link, because I added them). There are 5 functions from the new strings module that need to be added as well. I can tackle unless someone else was working on that already (I know strings is new in 2.0).

charris pushed a commit to charris/numpy that referenced this issue May 31, 2024
@bmwoodruff @charris
DOC: Added web docs for missing ma routines
e49e292 
This commit updates the routines.ma.rst file to enable web docs
for several routines in the `ma` module. Similar to numpy#23352
See numpy#21351 for a script to locate similar items in any module.

[skip actions] [skip azp] [skip cirrus]
charris pushed a commit to charris/numpy that referenced this issue May 31, 2024
@bmwoodruff @charris
DOC: Added web docs for missing strings routines
01fa042 
This commit updates routines.strings.rst to enable webdocs for
for several routings in the `strings` module. See numpy#21351 for a
script to automatically locate similar issues.

[skip actions] [skip azp] [skip cirrus]
@charris charris mentioned this issue May 31, 2024
Merged
@luxedo
Copy link
Contributor
luxedo commented Jun 6, 2024

Created gist of the script to run directly into a python shell.

@luxedo
Copy link
Contributor
luxedo commented Jun 6, 2024 •
edited
Loading

Missing Docstrings

np (12)

  • amax - Alias of max. Are examples needed?
  • amin - Alias of min
  • around - Alias of round
  • getbufsize
  • matrix_transpose
  • setbufsize
  • show_config
  • show_runtime
  • unique_all
  • unique_counts
  • unique_inverse
  • unique_values

np.char (7)

  • array
  • isalpha
  • isspace
  • mod
  • rfind
  • splitlines
  • startswith

np.ctypeslib (4)

  • as_array
  • as_ctypes
  • as_ctypes_type
  • load_library

np.lib (2)

  • add_docstring
  • add_newdoc

np.linalg (10)

  • cross
  • diagonal
  • matmul
  • matrix_norm
  • matrix_transpose
  • outer
  • svdvals
  • trace
  • vecdot
  • vector_norm

np.ma (6)

  • convolve
  • correlate
  • left_shift
  • put
  • reshape
  • take

np.rec (1)

  • find_duplicate

This was referenced Jun 6, 2024
Merged
Merged
Merged
Merged
Merged
Merged
Merged
@luxedo
Copy link
Contributor
luxedo commented Jun 6, 2024

I sent too many PRs already. I'll wait for review to add more.

@bmwoodruff
Copy link
Member

@luxedo If you put [skip actions][skip azp][skip cirrus] in your commit message, then proper GitHub actions will be skipped and your tests should pass.

@luxedo
Copy link
Contributor
luxedo commented Jun 6, 2024

Thank you! My bad.
I should not use [skip circle] right? The doctests run there?

@bmwoodruff
Copy link
Member
bmwoodruff commented Jun 6, 2024 •
edited
Loading

Correct. They have to be in the commit message as well. Putting them in the comments of the PR is not sufficient (learned that myself a few weeks ago). Any time you add more changes in another commit, you have to add these tags to the commit message to make sure the correct CI jobs are run.

@mattip
Copy link
Member
mattip commented Jun 6, 2024

Also please try to combine small example additions together into one PR

This was referenced Jun 8, 2024
Merged
Merged
@bmwoodruff bmwoodruff mentioned this issue Jul 9, 2024
Closed
@bmwoodruff bmwoodruff mentioned this issue Jul 17, 2024
Closed
@yashasvimisra2798
Copy link
Contributor
yashasvimisra2798 commented Sep 23, 2024 •
edited
Loading

I did like to add examples for the numpy.char.array, currently working on it.

@OmkarChoulwar
Copy link

Adding example code snippets to np.char.isspace function, currently in the process of adding it

@infinity-void6
Copy link

adding example code snippets to np.ma.convolve function currently in the process of adding it

@yashasvimisra2798 yashasvimisra2798 mentioned this issue Sep 23, 2024
Merged
@infinity-void6 infinity-void6 mentioned this issue Sep 23, 2024
Open
@shivkatira shivkatira mentioned this issue Sep 23, 2024
Merged
This was referenced Oct 19, 2024
Closed
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
04 - Documentation sprintable Issue fits the time-frame and setting of a sprint
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

DOC: add examples to ctypeslib m-clare/numpy
0