When talking about PEPs, we often refer to them only by their number (as in “PEP 705”), sometimes without a link or any information about their subject.
I don’t think it’s inherently a bad habit: if you actually know that PEP number, it’s the most concise of referring to it unambiguously, saving time for both the writer and the reader.
If you don’t, though, you tipically have to search it up – not necessarily to read the whole PEP, but just to figure out “ah yes, it’s that one!” or “oh right, it deals with that subject, written 15 years ago!”
In some discussions covering a lot of background with different PEPs involved, I found that this quickly led to a lot of back and forth between Discourse and the PEP pages, with the consequent loss of focus and time.
To make this experience easier, I’d like to present here a small Chrome extension I’ve developed for myself, if anyone here finds it useful: PEP Tooltip!
On hover, reveals a small tooltip containing key information[2] about this PEP (fetched from peps.python.org official API), with a link to the PEP;
Integrates well in both dark and light modes, and within various markdown / Discourse markups;
Handles new posts loaded when scrolling a page;
Lightweight, only requires read / update permission on discourse.python.org, does not collect any data whatsoever;
Totally open source (written in TypeScript); I wholeheartedly welcome any feedback or contributions on the GitHub repo!
While I only tested it on Chrome, I’m pretty sure it works well on any Chromium-based browser. I’m totally open to the idea of making a Firefox version if there is interest![3]
Hope this kind of message is welcome in Discourse Feedback; since it meta and Discourse-specific, I thought so, but I can move it to Python Help or anywhere
I tried to use various Unicode symbols and a custom SVG, I found this emoji the most usable (automatically adjusts to text size/style) and portable across plarforms (all Unicode characters are not), but this is open to change! ↩︎
Interesting! That looks useful too, but it seems to be a side-wide option (“required user level : Adminitrator”). I suppose automatically adding links to “PEP XXX” patterns would be feasible and not too controversial (and useful to all users by default!).
That doesn’t quite adress my goal though, which is to have information such as PEP title, status, date… directly in the page, without the need to click a link
That would only apply to PEP references on Discourse though, correct? What if some package’s docs referenced a PEP? Tooltips would help there as well I would think.
Ideally, documentation would link to references where appropriate [1] (PEPs, RFCs, etc) — e.g. in Sphinx one may use the PEP, RFC, CVE, etc roles in text. Replacing all patterns of PEP[- ][0-9]{,4} on every webpage might lead to annoying false-positives!
The extension is also limited to Discouse, both by design (I think it would be way too intrusive to alter text on all sites, and lead to false positives as Adam pointed out) and for technical reasons (for example, I use some Discourse CSS variables to handle well light vs. dark mode).
That said, I thought to extend it to other relevant sites such as GitHub, maybe some day!
I chose to only process text in messages, to avoid annoying tooltips showing up in unexpected places throughout the site (eg. in the posts lists, in the top-right menus…)
Post titles could be special-cased, though if a PEP number is mentioned in a title, it’s very likely to appear in the first lines of the message!
character[1] alongside each “PEP XXX” pattern in any discourse.python.org message;
