[docs] [sphinx] need to resolve cross-references for inherited/mixin methods

🚀 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

[01-vyom]

@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.

[stas00]

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!