Improve documentation for async programming
- Dominant language
- Python
- Stars
- 5.4k
- Forks
- 827
- Avg merge
- 9h 45m
- Merged PRs (30d)
- 58
Description
**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.
Contributor guide
Research direction
Start by locating the `toga.App.add_background_task()` API and the documentation for the `handlers` example. Review how generators, async callbacks, GUI updates, and native event-loop integration are currently described, then add the requested API docstring and how-to coverage. Done means newcomers can find guidance for background tasks without relying on Discord.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100