Fix docstrings

Sphinx>=3.1.0 doesn’t build our documentation for some reason (I guess our experimental and deprecated decorators are the devils, not sure though).

At first, as https://github.com/optuna/optuna/issues/1368 said, we were optimistic about this, i.e., we thought the next stable would work. However, it’s not happened yet. So it’s high time we dirtied our hands to enable the latest Sphinx.

~~The latest ongoing pull request is https://github.com/optuna/optuna/pull/1613.~~

[harupy]

After some digging, I found that the root cause is that sphinx calls python’s built-in inspect.signature with follow_wrapped=False when processing classes.

sphinx’s inspect.signature which internally calls python’s inspect.signature with follow_wrapped=False by default: https://github.com/sphinx-doc/sphinx/blob/5e6da19f0e44a0ae83944fb6ce18f18f781e1a6e/sphinx/util/inspect.py#L437

ClassDocumenter calls sphinx’s inspect.signature without follow_wrapped. https://github.com/sphinx-doc/sphinx/blob/38b868cc0d0583d9a58496cd121f0bc345bf9eaa/sphinx/ext/autodoc/__init__.py#L1401

The same thing occurs in update_annotations_using_type_comments: https://github.com/sphinx-doc/sphinx/blob/38b868cc0d0583d9a58496cd121f0bc345bf9eaa/sphinx/ext/autodoc/type_comment.py#L122

Hope this makes sense.

[harupy]

Filed a PR in the sphinx repo: https://github.com/sphinx-doc/sphinx/pull/8115 😂