beeware / beeware/beeware-docs-tools

Document protocols (especially callables) more clearly

Open
#246 2 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
2
Forks
17
Avg merge
1d 2h
Merged PRs (30d)
10

Description

### What is the problem or limitation you are having?

In Python, when you want to document a protocol for a callable, you define it as a class with a `__call__` method, and that's how it shows up in the docs.

screenshot of OnCloseHandler

Even for someone well-versed in Python mechanics, that's not the most intuitive way to show that what you *probably* want is a function / method.

The situation was *slightly* (but not much) better in Sphinx:

Screenshot of Sphinx

It at least put a note on all protocols (callable or otherwise) saying "Classes that implement this protocol must have the following methods / attributes:", which make it clear that this is a model to follow rather than an actual, existing class to use. And it's labeled as a protocol, not a class. As it stands in our current docs, the only thing telling you that is "Bases: Protocol", and you have to know what that means.

It's also listed as just a "class" in the sidebar:

Sidebar

(The Sphinx docs had no equivalent there, since things weren't labeled by type in the sidebar.)

### Describe the solution you'd like

It would be nice for protocols to be more clearly delineated from actual class definitions. Their "type" would ideally be "protocol" rather than "class", they should color-coded differently, and a note analogous to the one in Sphinx wouldn't hurt.

Additionally, it would be fantastic if *callable* protocols (that don't define any other attributes) weren't visually structured like classes at all, but like function definitions.

### Describe alternatives you've considered

There's nothing technically *wrong* with the status quo. It just follows the letter of the law while not clearly conveying the spirit.

### Additional context

I have no idea if this would be even remotely feasible to implement on our end; I expect it would have to be made upstream. If we *can* figure out how to implement it, it seems generally useful enough that we should consider publishing it as a plugin.

Contributor guide

Open the contributing guide

Research direction

Start by tracing how the current documentation renders protocols, callable protocols, and sidebar type labels; the issue provides screenshots but names no files or tests. Check whether these behaviors come from the local documentation tooling or an upstream dependency. Done means a concrete implementation path is identified for clearer protocol labeling, callable presentation, and an explanatory note, or the upstream limitation is documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.