Improve documentation for async programming

[samschott]

Is your feature request related to a problem? Please describe.
A frequent question on Discord is how to create tasks that run in the background and don't block the GUI. This is currently not covered in the documentation at all. While @freakboy3742 or others mostly promptly reply with useful instructions, many newcomers might not make it to the Discord channel in the first place. Improving the documentation will also reduce the burden of answering the same questions repeatedly.

Describe the solution you'd like
At the very least, we should add a doc string to the toga.App.add_background_task() API. I would argue that this topic also warrants a separate how-to guide, possibly covering the following topics (inspired by the handlers example):

1. Toga's convenience function toga.App.add_background_task().
2. Handlers in toga: the use of generators and async functions as callbacks in toga.
3. A warning about updating the GUI from background threads and the recommendation to use async programming instead. This will be very useful for people new to (GUI) programming.
4. A brief introduction to native event loop integration in toga. This is useful if people want to write their own asyncio code.

[freakboy3742]

+1. Completely agreed. MOAR DOCUMENTATION in general, but this topic specifically.

I've got any early draft of a new step in the BeeWare tutorial that covers this topic; but we also need topic and API documentation in Toga.

The one thing I'd add to your list here is that (3) probably needs to be more fundamental - not just about updating from background threads, but why long running blocking tasks are problematic. Most (observant) people will notice the problem pretty quickly; but unless you've got a history of GUI programming, you might not appreciate why.

[samschott]

Ok, in that case I will wait for your BeeWare tutorial first before staring to draft anything myself (or prodding someone on Discord to pick this up).

I am in general a little confused about which topics to cover in the BeeWare docs vs toga docs. I would have thought that topics which only concern a single tool should be covered by the docs of the specific tool and therefore would have seen this is a toga-only topic. How do you typically decide where docs should live? One can of course always have cross-references between the docs to reduce duplication…

I agree that we should also discuss why to avoid long running blocking tasks, this would be particularly useful for a beginner-friendly project :)

[freakboy3742]

I've just uploaded beeware/beeware#133, adding the async improvements to the BeeWare tutorial. I'd be interested in any feedback you may have.

As for why I've put that in the BeeWare tutorial - mostly because that's the point of entry to BeeWare as a project, and it's our first opportunity to seed in the mind of the audience the fundamentals of how GUI programming works, and the sort of accomodations that need to be considered when building your app.

That tutorial isn't intended to be a "full training course"; just something that plants the seeds of the fundamentals. Once Toga has more complete docs, I can foresee a future where the BeeWare tutorial includes links to more comprehensive details in the Toga docs.

[mhsmith]

Related:

• Document passing arguments to event handlers #2099