Docstring check
Author: sgugger
Pull request: yes

# What does this PR do?

This PR adds a new util script that checks docstrings documentation of the arguments match the signature. This first version only checks base objects (functions and classes) not class methods. It checks:
- that the defaults documented are the same as the signature
- applies our traditional formatting (numbers not in code blocks, all other objects in code blocks, default to None skipped)
- that the order of the parameters is the same in the docstring and in the signature
- that all arguments (except `*args` or `**kwargs` or private arguments) are documented

It also performs auto-fixing for all of those problems (with templates for arguments that are not documented). As you will see from the diff (and it only covers the objects where all arguments were documented!) this was direly needed and should help a lot in the future.

The auto-fix part is added in `make fix-copies` while the check is in `make repo-consistency`. Since the auto fixing adds templates sometimes (for non-documented arguments), the check will error if those templates haven't been replaced, so the CI tells us when something is wrong.

The script has been applied to all objects it could fully auto-fix, and there is a (long) list of objects where manual input is needed (because some arguments are not documented yet). This could be fixed progressively with a sprint involving the community (hacktoberfest is coming!), but at least we can ensure newly added objects are properly documented.

A couple of additional notes:
- this is only applied to objects that are in the public init and not ignored in the check that ensures all objects are documented.
- as said before this doesn't touch the method yet, only the class inits. Adding the methods will be done in a followup PR later on
- one can ignore a docstring from this check by adding a comment `# no-format` before the docstring (see for instance `TrainerCallback`)
- it is also possible to ignore the re-ordering of the arguments documentation (if there is a special order that makes more sense for the documentation) by adding a comment `# ignore-order` before the docstring (no example of this yet)
- since we have a lot of arguments with a default `None` in the signature but that are set to a value in the call (often for mutable arguments since default mutables are dangerous in Python) the check won't replace a documented default when the signature shows None.
- we also have a lot of default arguments that are defined by mathematical formulas, which make more sense than the actual value, so the check uses a small Python interpreter for math expressions to make sure to leave those alone (if they are accurate).
- some values are reformatted by Python: it wants `1e-05` instead of `1e-5` or `Resampling.Xxx` instead of `PILResampling.Xxx`. Those are minor changes we don't really care about (I think).

cc @amyeroberts since you were interested by this
cc the doc master @stevhliu and @MKhalusova for your information

Comments:
_The documentation is not available anymore as the PR was closed or merged._

> what happens if the docstring contains argument name(s) that are not signature?

Then the argument in the docstrings should be removed. The goal is to ensure consistency, and arguments not in the signature are often hidden for a reason (deprecated arguments for instance) or might even not be accepted (but end up in the docstring after a bad copy paste for instance). Will fix the behavior you flagged in a comment.

Feel free to ping me again for another review! 

Waiting for @ydshieh review when he is back from vacation.

Here is a second review where I found something to check:

- Previous `PILImageResampling.BICUBIC` now becomes `Resampling.BICUBIC` (beit image processor etc), similar to `Resampling.BILINEAR` (convnext image processor etc). Do you know why? There are quite of them, but you can find by search **`Resampling.**
- `**optional**` is changed to `**optional*`, but I think we want `*optional*` (in logit processor file)
- ``["
NOTUSED", "
NOTUSED"]`` become `['
NOTUSED', '
NOTUSED']` (list of str):  I am fine with it, but want to double check with you.
- There is `eps: int = 1e-6,` but I think type annotation is not the goal of this PR



Yes, the tool does not check for type annotations. Added something to catch the `**optional**` floating around.

As for the two other points, this falls under the last point of the description: some values are reformatted, but the tool will be consistent so I don't think it's a bad thing, it's just a different thing.

Let me know if you think of other things to add.

This is rebased and updated to main, would be cool to merge soon-ish if you're happy with this :-)

It turns out `PILImageResampling` is not from PIL but our internal code. So good to keep  `PILImageResampling`.

I think the discrepancy in values is due to the different versions of PIL, but I didn't manage to reproduce having 3 instead of the enum object printed.

For speed, it's a bit challenging to have the util only verify the files modified (like `make fixup`) instead of everything, since it's not based on file but on objects. Part of the slowness is also just importing everything from `transformers`.

Sounds good! Let's merge this PR.

Thanks for your efforts @sgugger!

EDIT: we'll merge the PR right after tomorrow's release to make sure we can fix if anything breaks. 

Merged! Thanks 🫡