Clarify API surface for Source/ListSource/TreeSource/Row/Node
- Dominant language
- Python
- Stars
- 5.4k
- Forks
- 827
- Avg merge
- 15h 39m
- Merged PRs (30d)
- 40
Description
### Discussed in https://github.com/beeware/toga/discussions/3759
We have a protocol definition for `Source`, API documentation for `ListSource` and `TreeSource`, and a topic guide that discusses custom data sources.
However, in all this documentation, the exact API surface for a custom `ListSource` and `TreeSource` (any, by extension, `Row` and `Node`) isn't clear.
If a user were to try and write a custom `ListSource` or `TreeSource`, it would be very difficult to do so, as the API contract for these classes isn't explicitly documented.
We should provide much clearer documentation of:
1. The API contract for `ListSource` and `TreeSource`
2. The list of notifications that a custom ListSource and TreeSource should generate to satisfy Table, Tree and DetailedList widgets.
Contributor guide
Research direction
Start with the existing Source protocol definition, ListSource and TreeSource API documentation, and the topic guide on custom data sources. Compare these with the Table, Tree, and DetailedList widget notification requirements, then document the custom ListSource and TreeSource contracts and the notifications they must generate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100