Notification: show build tip/warning messages on PR builds

[humitos]

It would be really good to find a way to show build "tip" and "warning" notifications on the rendered version of the documentation. This will make people reading the PR version of that documentation to be aware of potential issues on that particular build.

We could:

• show a small 🔔 icon somewhere in the page that lists all the notification
• show a notification (similar to the current one) below/above the current one with the notification we want to communicate (the background color could 🟡 or 🟦 depending if it's a warning or a tip

Example

This notification shown in the build's detail page (that most people don't see)

could be shown in the rendered version as:

Related:

• Build: new notification system for build notifications readthedocs.org#10598

[ericholscher]

This is a great idea. I agree build notifications on the build page are less likely to be seen. We could also email them or do site-wide notifications vs. just display on the build page. Finding the best way to get that info in front of people feels useful.

I had a similar idea, which is exposing a "build status" addon that just shows a little 🟢 🟡 🔴 status in the doc page. The goal here is basically to show "freshness" or answer the question "Is this the latest commit that has already been built?"

The main value here is in collaboration when you're actively updating the page and getting feedback. I keep having issues with PR previews where I push updates, let someone know it's updated, but the build hasn't completed yet and refreshed.

Overall, I think having more "status" info on the PR builds in some fashion is good. I don't think we want "in your face" notifications except for something like "The last build of this branch failed" kind of messaging (This could also be a useful place for the 🔴 status icon to present similar info).

[humitos]

exposing a "build status" addon that just shows a little 🟢 🟡 🔴 status in the doc page

I was thinking that if it's just the build status, we could include an UI element inside the "This page was created from a pull request build" notification and keep the notification and the status together in the same notification, since they are pretty related each other.

Edit: maybe we can just change the color of the "branch" icon and add title property that it's shown when hovering with clear explanation: "The latest version of this preview is still building", or similar.

[ericholscher]

Yea, I think there's a few ways to show the data. I don't feel strongly about the UX, but a simple initial version would be neat just as a proof of concept, then we can build from there.

[humitos]

I started playing with this and found two interesting things:

We had a bug in our code for builds.currents when not sending the url= parameter. I opened a PR for this at readthedocs/readthedocs.org#11068

exposing a "build status" addon that just shows a little 🟢 🟡 🔴 status in the doc page.

To implement the use case that @ericholscher is describing here we don't have to cache the addons API responses for any page on PR builds. This is because the response will be dynamic and will depend on the ongoing build. This may not be a problem since we expect to have very little requests from PRs and we expect the cache to be invalidated frequently (on each push), but it's something to keep in mind if we decide to move forward with the implementation of your use case.

[ericholscher]

Good point on the caching. It might be a use case for an additional API call for that addon if it's enabled or something -- but I agree, it's probably fine to just not cache PR builds in this case since they are hit way less often than production.

[humitos]

Now that we allowed anonymous access to the APIv3 (readthedocs/readthedocs.org#11485), I think we should be able to do a POC for this. We should be able to hit https://docs.readthedocs.io/en/stable/api/v3.html#builds-listing and get the latest build and check the finished field of the first result.

We will need to add a ?version_slug= query filter to the APIv3 endpoint first, tho.