Examples with explanations in doc

[Okroshiashvili]

It would be really helpful for newcomers to have example outputs and explanations in docs. For example, I spent few hours looking what [self] means in HTML output. I'm sure there will be other cases when there is something different than [self] and it's hard for newcomers to explain why their code spends most of the time there.

[joerick]

Yeah, great idea! Are there any other things that tripped you up as a newcomer?

[Okroshiashvili]

I guess, yes @joerick

For example, if a class defines __call__ method. There will be something... not sure what but...

You can start adding these two and if I will encounter anything else, I'll let you know