[DOC] Organize the API section (Package overview)

[wdevazelhes]

See comment #145 (comment)

EDIT: This issue is for organizing the API section (e.g. separating the weakly supervised algorithms and the supervised algorithms) (see comment below)

[bellet]

I was thinking that the generic class methods could also be briefly demonstrated in the user guide. Maybe for each part (supervised/weakly sup), we could have a first subsection called something like "General API" which explains input data to give to fit as done currently, as well as the transformer_ attribute and methods like metric, score_pairs and transform. Then the second subsection "Algorithms".

But I also agree that the Package overview section could be better structured

[wdevazelhes]

Oh OK yes I agree, it would fit nicely at the beginning of the User guides, I'll open a separate issue for that