General Outline for New Tutorials

[appeltel]

From bpo-30145 @1st1 has proposed the following general structure for the revised asyncio tutorials and documentation:

1. Tutorial
   a/ Why async IO?
   b/ async/await in Python
   c/ Simple example in asyncio (Tasks + sleep) + explanation
   d/ An example of using aiohttp
   e/ How asyncio works and what is the event loop
   f/ Tasks, asyncio.gather, wait_for, cancellation

2. Advanced Tutorial
   a/ A short primer on network IO
   b/ Let’s implement a memcache/redis driver using streams!
   c/ Let’s implement a memcache/redis driver with transports!

3. API reference — there are a few things we’ll need to restructure
   there.

The proposed structure for the tutorials makes sense to me, and looking at the structure of the python reference I think they might fit best as new tutorials in the HOWTO section.

[1st1]

The proposed structure for the tutorials makes sense to me, and looking at the structure of the python reference I think they might fit best as new tutorials in the HOWTO section.

I'm not sure I like the idea of moving tutorials to HOWTO. Part of me wants the user to just open asyncio docs and see everything grouped logically -- both tutorials and the API reference. Otherwise, I worry, that a lot of people will simply miss the tutorials.

[appeltel]

@1st1 - Makes sense - I'll go ahead and close #2 and then open a new PR with the tutorials as new subsections of the asyncio language reference. I was guided by the logging reference docs as a precedent where there is a box at the top pointing people to the tutorial, but just having the tutorial as the first section would be harder to miss, and I don't think it would make the other reference material harder to find.

[1st1]

@1st1 - Makes sense - I'll go ahead and close #2 and then open a new PR with the tutorials as new subsections of the asyncio language reference. I was guided by the logging reference docs as a precedent

Yeah, let's do it first in asyncio docs. If anything, when we finish our work here and create a PR to CPython, then if many people object we'll simply move the tutorial to HOWTO.