[wanted] explicit docs for inherited methods 
Author: stas00
Pull request: no
Labels: name: WIP

# 🚀 Feature request

The HF approach is to unroll most of the code for the ease of understanding, but somehow this is not the case with docs.

If possible, could we explicitly add documentation for inherited methods in the specific model documentation page? 

e.g. why https://huggingface.co/transformers/model_doc/t5.html doesn't have `T5ForConditionalGeneration.generate` documented - sure one eventually figures out it's https://huggingface.co/transformers/main_classes/model.html#transformers.generation_utils.GenerationMixin.generate but why make user's life so difficult when the docs are autogenerated anyway.

In the worst case there could be an entry for `T5ForConditionalGeneration.generate` with the link to https://huggingface.co/transformers/main_classes/model.html#transformers.generation_utils.GenerationMixin.generate, but that is not ideal since one has to leave the main doc of the model, which makes it much harder to jump around its different parts.

IMHO, it'd greatly improve user's experience to have all the functionality documentation supported by a model in one page of that model.

And xrefs are super-useful too, e.g. [t5 pre-amble](https://huggingface.co/transformers/model_doc/t5.html#overview) mentions  `T5ForConditionalGeneration.generate `but it's not linked to anywhere.

Thank you!
 
@sgugger, @LysandreJik 

Comments:
I don't agree on an always-document-everything basis, as the documentation page of each model is already quite long (which may be the reason not a lot of people seem to be reading them...) In the case of generate, since there is no link to the part where the generate method is documented, we could add the documentation of the generate method there, but in the case of tokenizers for instance, I prefer our approach where we document just the main methods in the subclasses and point to the superclass for less important ones.
Which again also goes in the direction of documenting generate in the models that implement it, so why not go with it. I don't think it should be harder than adding `generate` to the members field, though sphinx might not like `GenerationMixin`. If anyone wants to give it a try, I'll happily review a PR.

`generate` was just an example, so let's not solve just a sub-case if possible.

As mentioned in OP if you feel that including full docs is too much - a short entry that links to the super class or mixin's method is a satisfactory solution, but the user shouldn't hunt for where that entry might be elsewhere. 

Also for methods such as `T5ForConditionalGeneration.generate` mentioned in free prose it'd be awesome to have it linked to the right doc entry. I understand it should happen automatically with sphinx if there is an actual entry to link to. 

> the documentation page of each model is already quite long (which may be the reason not a lot of people seem to be reading them...)

I don't know what you mean by "not a lot of people seem to be reading them" - do you imply that users ask a lot of questions that are already answered by the existing documentation or do you have some other way to measure the "not a lot" part?



> I don't know what you mean by "not a lot of people seem to be reading them" - do you imply that users ask a lot of questions that are already answered by the existing documentation

Yes, I was implying exactly that. For the general rule, I'd keep it to: main parts of the API of a class should be documented in which class (within reasons) and more minor parts should be documented once in the superclass/mixin with a link from all the subclasses (like what is done for `Tokenizer`)


I agree the process is long an feels like a lot of unnecessary steps.

>> I don't know what you mean by "not a lot of people seem to be reading them" - do you imply that users ask a lot of questions that are already answered by the existing documentation
> Yes, I was implying exactly that. 

Do we have a way to reach out and ask why users don't per-use docs before asking questions? 

Is this:

* an issue of the quality/readability/navigationability of the docs
* users are just lazy (as a virtue)
* users don't know that there are docs to search through
* the search engine doesn't have the smarts to show most relevant info and shows too many irrelevant hits? many docs search engines are pretty crappy in my experience. It's usually the best to use google with: 

`"my search query" site:https://huggingface.co/transformers/`

to find the best information. (swap in whatever other docs site you need, I wasn't singling out transformers, it was just an example)

> For the general rule, I'd keep it to: main parts of the API of a class should be documented in which class (within reasons) and more minor parts should be documented once in the superclass/mixin with a link from all the subclasses (like what is done for Tokenizer)

That works 100% for me. 

What needs to be done to make this happen? Definitely no rush.

I don't know whether this helps, but when I managed a huge open source project many years back I trained our users to per-use docs by almost never replying with the repeat information they requested but with a direct link to where it was in the documentation. Over time it was very clear to the community that the information is available in the docs and less and less questions were asked and more and more one line answers with the link to the right info were posted by various users of that community.

When one answers in clear text it signals users that the information is in your brain and not outside of it.

That is just how my experience had been, YMMV.

This issue has been automatically marked as stale and been closed because it has not had recent activity. Thank you for your contributions.

If you think this still needs to be addressed please comment on this thread.

@sgugger, how do we resolve this - please let me know if I can be of help.

I think we should agree to disagree on this point. I didn't see anything in the last survey that showed a strong desire from the user to have the documentation of each model page be even longer, quite the opposite, so I stand by what I said with the generic methods like `generate` be documented in the base classes unless they have some model-specific behavior that needs to override that documentation. It's the same for the tokenizer encode and call methods.

I think there are two different possibilities here:
1. duplicating content - you disagree with - OK
2. having a placeholder with a link to the main location of this entry

For example, when documentation refers to `T5ForConditionalGeneration.generate` it could:
1. link directly to the general `generate` doc entry
2. link to an entry `generate` in the t5 doc which will link to the main location of this entry

Why make the user work extra hard searching for something, when it can be automated and get the user what they need in 1 or 2 quick clicks.

I'm not asking for a hypothetical nice-to-have feature, I often find myself frustrated when I can't quickly link to a method when I address someone's Issue and have to search for it. So it's a very selfish request. And I'm willing to work for it, since it'll save my time and minimize frustration where it doesn't have to happen.

> For example, when documentation refers to T5ForConditionalGeneration.generate it could:
> 1. link directly to the general generate doc entry

I am not sure I know how to do that in sphinx, but if it's possible, I'm all for it!

> 2. link to an entry generate in the t5 doc which will link to the main location of this entry

This one will require writing a custom docstring for the generate method of T5. Probably more possible and can be automated with a decorator to use on the classes with a generate method I think.

Great. I will research it then and report back if I find a way. 

Thank you for your feedback, @sgugger