Skip to content

Add check that all parameters are properly documented #7758

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
amueller opened this issue Oct 26, 2016 · 10 comments · Fixed by #9206
Closed

Add check that all parameters are properly documented #7758

amueller opened this issue Oct 26, 2016 · 10 comments · Fixed by #9206

Comments

@amueller
Copy link
Member

We should steal stuff from https://github.com/mne-tools/mne-python/blob/master/mne/tests/test_docstring_parameters.py
as @agramfort pointed out.
@amueller
Copy link
Member Author

Also see #3791

@raghavrv raghavrv mentioned this issue Oct 28, 2016
Closed
@neerajgangwar
Copy link
Contributor

@amueller I modified mne-python code and tried it on scikit-learn. There are 225 places where there is an issue in docstring.

The commit is present here. Feedback to make it better? :)

@jnothman
Copy link
Member

Perhaps make a pull request so we can see to what extent these can be easily fixed. I recall writing a script to list these inconsistencies once (perhaps I have it as a Gist) but that there were some tricky cases.

@neerajgangwar
Copy link
Contributor

@jnothman Earlier I kept the script in sklearn/tests directory as a testcase. But the test suite was failing for obvious reasons. So I decided to move it to sklearn/utils for now but I am not able to run the script. It's giving following error

Traceback (most recent call last):
  File "check_docstring_parameters.py", line 3, in <module>
    from numpydoc import docscrape
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpydoc/__init__.py", line 3, in <module>
    from .numpydoc import setup
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpydoc/numpydoc.py", line 32, in <module>
    from sphinx.util.compat import Directive
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/Sphinx-1.4.1-py2.7.egg/sphinx/util/__init__.py", line 16, in <module>
    import tempfile
  File "/home/neeraj/Applications/anaconda/lib/python2.7/tempfile.py", line 35, in <module>
    from random import Random as _Random
  File "/home/neeraj/Projects/github/scikit-learn/sklearn/utils/random.py", line 5, in <module>
    import numpy as np
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpy/__init__.py", line 184, in <module>
    from . import add_newdocs
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpy/add_newdocs.py", line 13, in <module>
    from numpy.lib import add_newdoc
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpy/lib/__init__.py", line 8, in <module>
    from .type_check import *
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpy/lib/type_check.py", line 11, in <module>
    import numpy.core.numeric as _nx
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpy/core/__init__.py", line 58, in <module>
    from numpy.testing.nosetester import _numpy_tester
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpy/testing/__init__.py", line 12, in <module>
    from . import decorators as dec
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpy/testing/decorators.py", line 21, in <module>
    from .utils import SkipTest
  File "/home/neeraj/Applications/anaconda/lib/python2.7/site-packages/numpy/testing/utils.py", line 15, in <module>
    from tempfile import mkdtemp, mkstemp
ImportError: cannot import name mkdtemp

I can't seem to figure out a way to run it from sklearn/utils directory. I searched for the error and found this issue #4620. I am able to run from tempfile import mkdtemp, mkstemp from all directories but sklearn/utils.

@raghavrv
Copy link
Member

Earlier I kept the script in sklearn/tests directory as a testcase. But the test suite was failing for obvious reasons. So I decided to move it to sklearn/utils for now but I am not able to run the script. It's giving following error

I suggest that you move back the test to the sklearn/tests directory and make a PR... It's easier to review a PR than a commit or a traceback...

It's okay if the CI fails... We can address the failures (which is the whole point of this issue) one by one :)

@neerajgangwar neerajgangwar mentioned this issue Oct 30, 2016
Closed
@neerajgangwar
Copy link
Contributor

@raghavrv Thanks ! Created a PR and marked it WIP.

@neerajgangwar neerajgangwar mentioned this issue Nov 20, 2016
Closed
@bsipocz bsipocz mentioned this issue Nov 24, 2016
Open
@jpeacock29
Copy link

A few particular cases (a subset of those referenced in #7901) where documentation is missing:

  • LogisticRegression.classes_
  • MultinomialNB.classes_

@jnothman
Copy link
Member

jnothman commented Dec 28, 2016 via email

@bsipocz
Copy link
Contributor

bsipocz commented Jan 22, 2017 •
edited
Loading

This may be relevant to you, too: pydocstyle can now check for numpy docstyle conventions: PyCQA/pydocstyle#226

@jnothman
Copy link
Member

Thanks @bsipocz, this is interesting, and a little useful. I will comment on that PR.

@agramfort agramfort mentioned this issue Jun 7, 2017
Closed
@raghavrv raghavrv mentioned this issue Jun 23, 2017
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
6 participants
@jnothman @amueller @neerajgangwar @bsipocz @jpeacock29 @raghavrv