search

asyncio-docs / cpython-aiodocs

This is a fork of CPython to work on an updated asyncio documentation for Python 3.7. Don't use it for any other purpose.
Other
0 stars 0 forks source link

General Outline for New Tutorials #1

Open appeltel opened 7 years ago

appeltel commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

@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 commented 7 years ago

@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.