-
-
Notifications
You must be signed in to change notification settings - Fork 25.8k
[WIP] Add a script to check discrepancies between function parameter list and function docstring parameters #7793
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.
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
Conversation
If we are to consider including this, we would have to do one of:
Please choose one. Thanks! |
Feature request: list args present in docstring but not in signature separately from the reverse case. |
(And what I'd really like to see in this vein is a list of attributes ending |
… the opposite case
@jnothman Made changes to list args present in docstring but not in signature from the opposite case. Regarding including the script, how do we go about running this as a separate process that includes numpydoc dependency? |
Sorry for the unclarity, I meant as a separate Travis run, for instance. We first should see whether we can / should fix these. |
FWIW, here are the current failures where numpydoc is available:
|
The error messages are currently missing class names where method docstrings are the problem. |
What would be really cool: If instead of just listing the errors, this could (have a mode to) actually write an initial diff file that patches the errors (adding a blank entry in approximately the right place for undocumented params; dropping the entire param description where the docstring has excess). This would make inspecting and fixing the issues so much easier. Btw, we should not be checking anything in externals (although it looks like Joblib needs this kind of quality assurance). |
That's probably the right solution. |
@jnothman If I run the script from
|
$ nosetests sklearn/tests/test_docstring_parameters.py |
It's giving an error. Not able to import |
You probably need to exclude sklearn.externals from these checks because that's the responsibility of packages included there to fix these problems. |
numpydoc needs to be installed. If we go ahead with this PR, we will want to move numpydoc to sklearn.externals as pointed out by @jnothman. |
@lesteve I had What all needs to be done to move it to |
Hm so we want to add the optional and ignored |
I think |
and makes it clearer |
I moved
Same with AppVeyor. |
See #7355 regarding the numpydoc upgrade... |
Complies with numpydoc to improve rendering and automatic quality assurance such as scikit-learn#7793. Affects listings of Parameters Attributes, Returns. Performed with the help of: grep -nE '^( )+[a-zA-Z][a-zA-Z0-9_]*: ' sklearn -R | grep -v -e externals -e tests | grep -v -e default: -e else: -e Warning: -e Note: -e TRAIN: -e Default: -e True: -e False: -e DOI: -e In: | gsed 's|\([^:]*\):\([0-9]*\):\([^:]*\):\(.*\)|--- a/\1\n+++ b/\1\n@@ -\2,1 +\2,1 @@\n-\3:\4\n+\3 :\4|' | git apply --unidiff-zero -
Complies with numpydoc to improve rendering and automatic quality assurance such as scikit-learn#7793. Affects listings of Parameters Attributes, Returns. Performed with the help of: grep -nE '^( )+[a-zA-Z][a-zA-Z0-9_]*: ' sklearn -R | grep -v -e externals -e tests | grep -v -e default: -e else: -e Warning: -e Note: -e TRAIN: -e Default: -e True: -e False: -e DOI: -e In: | gsed 's|\([^:]*\):\([0-9]*\):\([^:]*\):\(.*\)|--- a/\1\n+++ b/\1\n@@ -\2,1 +\2,1 @@\n-\3:\4\n+\3 :\4|' | git apply --unidiff-zero -
* DOC insert spaces before colons in parameter lists Complies with numpydoc to improve rendering and automatic quality assurance such as #7793. Affects listings of Parameters Attributes, Returns. Performed with the help of: grep -nE '^( )+[a-zA-Z][a-zA-Z0-9_]*: ' sklearn -R | grep -v -e externals -e tests | grep -v -e default: -e else: -e Warning: -e Note: -e TRAIN: -e Default: -e True: -e False: -e DOI: -e In: | gsed 's|\([^:]*\):\([0-9]*\):\([^:]*\):\(.*\)|--- a/\1\n+++ b/\1\n@@ -\2,1 +\2,1 @@\n-\3:\4\n+\3 :\4|' | git apply --unidiff-zero - * DOC fix numpydoc format for param
…arn#7920) * DOC insert spaces before colons in parameter lists Complies with numpydoc to improve rendering and automatic quality assurance such as scikit-learn#7793. Affects listings of Parameters Attributes, Returns. Performed with the help of: grep -nE '^( )+[a-zA-Z][a-zA-Z0-9_]*: ' sklearn -R | grep -v -e externals -e tests | grep -v -e default: -e else: -e Warning: -e Note: -e TRAIN: -e Default: -e True: -e False: -e DOI: -e In: | gsed 's|\([^:]*\):\([0-9]*\):\([^:]*\):\(.*\)|--- a/\1\n+++ b/\1\n@@ -\2,1 +\2,1 @@\n-\3:\4\n+\3 :\4|' | git apply --unidiff-zero - * DOC fix numpydoc format for param
…arn#7920) * DOC insert spaces before colons in parameter lists Complies with numpydoc to improve rendering and automatic quality assurance such as scikit-learn#7793. Affects listings of Parameters Attributes, Returns. Performed with the help of: grep -nE '^( )+[a-zA-Z][a-zA-Z0-9_]*: ' sklearn -R | grep -v -e externals -e tests | grep -v -e default: -e else: -e Warning: -e Note: -e TRAIN: -e Default: -e True: -e False: -e DOI: -e In: | gsed 's|\([^:]*\):\([0-9]*\):\([^:]*\):\(.*\)|--- a/\1\n+++ b/\1\n@@ -\2,1 +\2,1 @@\n-\3:\4\n+\3 :\4|' | git apply --unidiff-zero - * DOC fix numpydoc format for param
Closing this as I am not able to contribute to this for the time being. |
…arn#7920) * DOC insert spaces before colons in parameter lists Complies with numpydoc to improve rendering and automatic quality assurance such as scikit-learn#7793. Affects listings of Parameters Attributes, Returns. Performed with the help of: grep -nE '^( )+[a-zA-Z][a-zA-Z0-9_]*: ' sklearn -R | grep -v -e externals -e tests | grep -v -e default: -e else: -e Warning: -e Note: -e TRAIN: -e Default: -e True: -e False: -e DOI: -e In: | gsed 's|\([^:]*\):\([0-9]*\):\([^:]*\):\(.*\)|--- a/\1\n+++ b/\1\n@@ -\2,1 +\2,1 @@\n-\3:\4\n+\3 :\4|' | git apply --unidiff-zero - * DOC fix numpydoc format for param
…arn#7920) * DOC insert spaces before colons in parameter lists Complies with numpydoc to improve rendering and automatic quality assurance such as scikit-learn#7793. Affects listings of Parameters Attributes, Returns. Performed with the help of: grep -nE '^( )+[a-zA-Z][a-zA-Z0-9_]*: ' sklearn -R | grep -v -e externals -e tests | grep -v -e default: -e else: -e Warning: -e Note: -e TRAIN: -e Default: -e True: -e False: -e DOI: -e In: | gsed 's|\([^:]*\):\([0-9]*\):\([^:]*\):\(.*\)|--- a/\1\n+++ b/\1\n@@ -\2,1 +\2,1 @@\n-\3:\4\n+\3 :\4|' | git apply --unidiff-zero - * DOC fix numpydoc format for param
…arn#7920) * DOC insert spaces before colons in parameter lists Complies with numpydoc to improve rendering and automatic quality assurance such as scikit-learn#7793. Affects listings of Parameters Attributes, Returns. Performed with the help of: grep -nE '^( )+[a-zA-Z][a-zA-Z0-9_]*: ' sklearn -R | grep -v -e externals -e tests | grep -v -e default: -e else: -e Warning: -e Note: -e TRAIN: -e Default: -e True: -e False: -e DOI: -e In: | gsed 's|\([^:]*\):\([0-9]*\):\([^:]*\):\(.*\)|--- a/\1\n+++ b/\1\n@@ -\2,1 +\2,1 @@\n-\3:\4\n+\3 :\4|' | git apply --unidiff-zero - * DOC fix numpydoc format for param
Reference Issue
Fix #7758
What does this implement/fix? Explain your changes.
Add a script to check if there is a discrepancy between function parameter list and parameter list specified in function docstring
Any other comments?
Requires
numpydoc
package