DOC: Add "Examples" to docstrings #7168
Comments
WarrenWeckesser
added
Documentation
|
I am a newbie here. I exactly do not understand what the task is. Are the above commands do not have relevant examples for them? |
|
@pssk1988 Yes. The docstrings of those functions do not have an "Examples" section. The docstring standard that scipy tries to follow is https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt; in particular, "Sections" defines the sections that should be included in a docstring. "Examples" is the last section described in the docstring standard. According to the numpy docstring standard, "Examples" is an optional section, but many of us think it is a very important section, so we would like to ensure that as many functions as possible include it. |
|
@WarrenWeckesser Okay. Thats interesting! I will take up a section of them, probably start with simpler ones. |
|
I just started to add to examples. I forked scipy and performed I know I can do |
There doesn't appear to be an example of an Examples section in that reference. Could someone add a few examples to this issue illustrating the desired format for the section to follow? E.g. where does it go relative to the other sections? |
|
I've casually browsed through the examples in the current docs. It looked like that it comes at the very end after notes and references and Added in version x.xxx. But I'm not sure if this was intentional. It doesn't seem like this behavior is consistent. I would like to correct the recent examples if this was not the case. To me before notes and references seems a better place content wise but if somebody just looks up the docstring on the prompt, the examples show up as the last thing which is also good avoiding the scroll in case of long Notes sections. |
|
The "Examples" section is the last section. My understanding is that the recommended order of the sections in the docstring is the same as the order they are described at https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections. I'm pretty sure that's the intent, and that's what we've been doing for years. Any exceptions to that were probably accidental. |
|
@WarrenWeckesser This is my first contribution to an issue, so I started with a simple one. If it caters to the docstrings, how should I ask for a merge? numpy.average()"""The following module describes how to use
the average function of the numpy class"""
# From the existing set of classes we import numpy
import numpy as np
# We can rename numpy as np. Once may use anything
# -----METHOD 1-----
"""What is Average?
average = [Sum of all the elements of array]/[Number of elements in array]"""
# Let us declare an array of integers as follows
data = [1,2,3,4]
# Let us store the average in a variable 'av'
av = np.average(data)
print('The average using Method 1 is:', av)
# -----METHOD 2 - Weights -----
"""What is Weighted Average?
Given data=[1,2,3,4] and weight=[0.1,0.2,0.3,0.4]
average = [(1*0.2)+(2*0.2)+(3*0.3)+(4*0.4)]/[0.1+0.2+0.3+0.4]
"""
# We are going to use the same data as in METHOD 1
# Here we are going to have weight as [0.1,0.2,0.3,0.4]
weight_array = [0.1,0.2,0.3,0.4]
"""SYNTAX for Weighted Average
Weighted_Average = numpy.average(<data_name>, weights = <weight_array>)
Remember, here, 'weights' is a Python Keyword"""
weighted_av = np.average(data, weights = weight_array)
print('The Weighted Average using Method 2 is: ', weighted_av) |
|
@ss-is-master-chief Roughly summarizing:
The branch creation is really important because if later on you would like to do something else then we have to sort out subtle conflicts between the master of SciPy and your master branch. Hence, to keep things contained we work in branches and only merge if we are fully sure that it doesn't break anything. Please have a look at the similar function docstrings for examples. However note that |
|
@ilayn Could you suggest me some functions which I could work upon? |
|
@ss-is-master-chief Pick your favorite from the list above 😃 (except the linalg ones I'm about to submit a PR for them) |
|
Suggestion: may we make an up-to-date list of uncovered functions? Thank you! :) |
The list at the top of this issue is pretty much up to date, only #19433 is not accounted for. From what I see, there are currently two PRs addressing this issue: #19434 and #19058. Any other function you are very much welcome to have a look at :). |
lucascolley
added
the
sprint
towards scipy#7168 Co-authored-by: Lucas Colley <lucas.colley8@gmail.com>
towards scipy#7168 Co-authored-by: Daniel Schmitz <40656107+dschmitz89@users.noreply.github.com>
lucascolley
removed
the
sprint
|
Can someone update the last line of the issue description from |
|
sure, done |
towards scipy#7168 Co-authored-by: Lucas Colley <lucas.colley8@gmail.com>
towards scipy#7168 Co-authored-by: Daniel Schmitz <40656107+dschmitz89@users.noreply.github.com>
towards scipy#7168 Co-authored-by: Lucas Colley <lucas.colley8@gmail.com>
towards scipy#7168 Co-authored-by: Daniel Schmitz <40656107+dschmitz89@users.noreply.github.com>
scipy#19434. What does this implement/fix? Adds example for interpolate.spalde [skip actions] [skip cirrus]
scipy#19434. What does this implement/fix? Adds example for interpolate.spalde. Fixes dosctrings to pass doc build and refgude-check. [skip actions] [skip cirrus]
… of scipy#19434. What does this implement/fix? Adds example for interpolate.spalde and unifies descriptions along the docstrings. Fixes dosctrings to pass doc build and refgude-check. [skip actions] [skip cirrus]
scipy#19434. What does this implement/fix? Adds example for interpolate.spalde [skip actions] [skip cirrus]
scipy#19434. What does this implement/fix? Adds example for interpolate.spalde. Fixes dosctrings to pass doc build and refgude-check. [skip actions] [skip cirrus]
… of scipy#19434. What does this implement/fix? Adds example for interpolate.spalde and unifies descriptions along the docstrings. Fixes dosctrings to pass doc build and refgude-check. [skip actions] [skip cirrus]
and others
Many of the functions in scipy do not include examples in their docstrings. Even a simple example can be helpful for a new user, so we should try to include examples wherever possible.
A script called
find_functions_missing_examples.pyis now maintained in my github repositoryanalyze-scipy-code. This script reports the names of functions that are missing the "Examples" section.Below is the output that I get when run with the current master branch. Some of these functions have proper docstrings, so all they need is the addition of an "Examples" section containing one or more illustrative examples. Many of them, however, do not comply with the numpy docstring guidelines, and may be missing the "Parameters" and "Returns" sections. In particular, the docstrings of many of the functions in
scipy.specialare quite terse. Anyone who works on this task should ensure that the final docstring complies with the guidelines. See, for example, #7148, where the sections "Parameters", "Returns" and "Examples" were added to the docstring ofscipy.special.gamma.I have added the tag "good first issue" to this task, because it is usually very easy to add one or two examples to a function. (How to edit the docstring of the functions in
scipy.specialis not obvious, but take a look at #7148 or #7143 for examples.) The tag does not mean it will be easy to complete this task. As you can see below, there is a lot of work to be done! Anyone who wants to help should feel free to pick a function or two to work on.The script ignores functions that have the string "is deprecated" in their docstring. The names of other functions that should be ignored can be added to the list
skip. If you find such a function, add a comment about it here.Functions missing "Examples" (last updated 26-May-2024):
(This issue was created March 13, 2017. At that time, version 0.19.0 had just been released a few days earlier. When I run this script on that version (with
'fft'removed frommodules), it finds 674 functions without examples.)Note: if your PR only adds documentation, please add
[docs only]on a new line in the commit message. This will help save our CI credits.The text was updated successfully, but these errors were encountered: