[docs] Adding Examples to Documentation

[Eli Bendersky]

> A bit ago, after talking with Guido on the the core developers group, I was
> working on examples for areas of the documentation that I felt would be
> helpful to have examples for (particularly itertools, but also functools and
> os).  I received some feedback from the group once I submitted some new
> documentation, but it never moved much further.
>
> I was hoping to start a discussion here to see whether others felt that
> examples of code usage would be worthwhile, and if so, how we could organize
> these into sections.
>
> Taking itertools as an example, there are a lot of great implementation
> details, as well as recipes that combine the various functions, but the
> actual examples of how to use the library are small and potentially
> confusing for someone using the library for the first time.  I know people
> go to the documentation for various reasons, so I don't think removing these
> sections would be wise, but what do you all think about adding an "Example
> Usage" section that lists some concise and easy ways to get up and running
> with the library?
>

Many documentation pages have "example" sections with usage samples.
When these make sense and can be made sufficiently small and
expressive, they're very helpful. So I suggest to propose something
more concrete. I.e. create an issue in the bug tracker and add a patch
with some examples for the module you want to document. Add relevant
persons to the nosy list
(http://docs.python.org/devguide/experts.html), and hopefully someone
will take a look.

Eli