[docs] [sphinx] need to resolve cross-references for inherited/mixin methods
Author: stas00
Pull request: no
Labels: name: Good First Issue

name: Good Second Issue

# 🚀 Feature request

`T5ForConditionalGeneration` inherits `generate` from `PreTrainedModel` via `GenerationMixin`.

Currently in our docs if we write:
```
for more info see :meth:`transformers.T5ForConditionalGeneration.generate`
```
it doesn't get resolved in the html docs (it doesn't get a xref link, but leaves it as a text)

Neither `transformers.PreTrainedModel.generate` gets resolved - which is the super-class that has this method.

But since it's a mixin and actually comes from `transformers.generation_utils.GenerationMixin` the only way to get the cross-reference turned into a working link is to write:
```
for more info see :meth:`transformers.generation_utils.GenerationMixin.generate`
```
which is slow and complicated to figure out and non-intuitive. And this was just one example.

Both @sgugger and I tried to find a sphinx configuration to make it resolve `transformers.T5ForConditionalGeneration.generate` to `transformers.generation_utils.GenerationMixin.generate` and point to the right doc entry, but didn't succeed.

This could be related to the fact that we don't generate docs for inherited methods and only document them in the parent class. We want to keep it that way but to be able to cross-reference the inherited methods in the docstrings.

If you perhaps have an expertise in sphinx and could help us resolve this it'd be absolutely amazing!

T5 was just an example, this is needed for dozens of models.

If there is no way to currently do it you could also submit a feature request with sphinx and take a lead on following through for this new feature to be added. 

Bonus:

As explained above we don't duplicate inherited methods docs, but it'd be really useful to list the inherited methods which didn't get documented in the sub-classes, e.g.: https://huggingface.co/transformers/model_doc/t5.html#tft5forconditionalgeneration could have a brief entry:
```
Inherited methods: generate, greedy_search, sample, beam_search, beam_sample, group_beam_search
```
with cross-references to the corresponding full doc entries in the super-class. Of course, while this could be created manually, it'd be very difficult to maintain - so we need to this to be autogenerated.

Thank you!

Related issues/prs:
- https://github.com/huggingface/transformers/pull/11049
- https://github.com/huggingface/transformers/issues/9202

Comments:
@stas00 can I try this?

Yes, please!

You run `make docs` to build the docs and then the build ends up under `docs/_build/html/`.

You will need to run `pip install -e .[docs,all]` first to get all the packages installed.

@stas00 can I work on this?

I don't know where @frankhart2018 is with his experiments, as 3 weeks have passed, so probably there is no harm in having another person try to solve this. So please go for it, @01-vyom. Thank you!

@stas00 Sorry, I won't be able to work on this issue as I am working on some other problems. You can review any other PR for this issue. 

Doesn't look like anybody found a solution, closing this one for now.