Ensure that parameters are documented

[bsipocz]

I think we should consider implementing (copying over) the solution of sklearn to make our documentation better (and enforce to keep it that way).

scikit-learn/scikit-learn#7758

I've already made some fixes in #5503, but it would be very nice to see that we can force not to diverge.

[mhvk]

(from #5503) -- sounds good to try to use any solution they come up with!

[MSeifert04]

I haven't looked at the details but it raises the interesting question if we really want all functions to contain parameter-lists (i.e. aliased or deprecated functions) and how we should handle decorated functions, where the signature is explicitly changed or removed?

[bsipocz]

@MSeifert04 - There can be exceptions, especially for deprecated things, but we should aim to spot the odd case of forgetting to add/update the docstring.

[bsipocz]

In a related issue (gammapy/gammapy#325), @cdeil mentions https://github.com/PyCQA/pydocstyle as a tool we might be able to use for this (similarly to our pycodestyle checks). However it's not yet clear when it will work with numpydoc style docstrings.

[hamogu]

I had a working version of something very similar to this in #1196, but then the require module was moved into astropy-helpers under my feet and at the time I could not figure out how to make a PR to astropy-helpers and then see the effects in astropy for testing, so I just never did it.

[cdeil]

Support for the numpy docstring convention recently landed in pydocstyle:
PyCQA/pydocstyle#226

It's not released yet, but if you install the dev version, then it's possible to use already, e.g.

pydocstyle --convention=numpy --add-ignore=D410 astropy/nddata

I don't have time to clean up stuff or to help improve that tool. I just tried if for 5 min and reported one false positive issue: PyCQA/pydocstyle#230

IMO anyone that has time to work on docstring checkers should consider contributing to that tool instead of 100s of projects rolling their own.

[bsipocz]

Thanks @cdeil for pushing for this. I totally agree that using tools like pydocstyle is the way forward. I plan to work a bit on this on pep8 before the new release as a clean-up, but it's totally fine by me if someone is faster and beat me to it.

[bsipocz]

Undocumented parameters came up again as an issue (#7608 (comment)), thus I'll try to get something working by 3.1

[MSeifert04]

It would be very helpful to get this working. However in the case of #7608 the parameters are documented. 😄

[pllim]

Since this keeps resurfacing once in a while, I added a "sprint" label in hope that we'll get to it sooner than later. 🤞

[pllim]

Removing milestone...

[bsipocz]

Thanks. this slipped through, though still can be addressed after feature freeze given it's documentation ;)