[Buildbot-devel] Waterfall HTML styling

[Brian Warner]

> The waterfall output is informational, but aesthetically pretty crummy, 
> in my humble opinion.

Hear Hear! :)

Yeah, it's meant to be information-dense, not pretty. The results are kinda
ugly. It's even worse than it ought to be, the table layout I went with seems
to randomly drop cell-borders on most browsers, so that you don't even get to
see the "grid" that the boxes are supposed to be a part of.

> Specifically, each box needs a class representing the type of step (eg., 
> "testing", "compile") and the outcome ("success, "failure", etc.). The 
> other cells also need classes. Finally, the page needs to reference, 
> with <link>, a named style sheet.

Yeah, that makes sense to me. One limitation is that there's no actual "type"
for each step: they all have names (which may come from the BuildStep class
that produced it), but those names are not taken from a fixed list or
anything. So your step-styles would need to be able to survive in the face of
unknown names.

I would very much like to see the grid layout handled with CSS instead of
that big table. My HTML skills certainly aren't up to the task, but I suspect
it may be non-trivial even for a CSS wizard, because of the way the cells are
generated (if you take a look at the code, you'll note that there is a phase
which generates the grid with a bunch of "holes" where no event happened,
then a second phase to figure out how to increase ROWSPAN= values to merge
the holes and figure out which time-windows each event fits in.. that code is
pretty nasty).

Finally, keep in mind that the Waterfall page is all about showing
time-oriented events. There will be a separate page to show just the most
recent build for each Builder, which can be much much simpler (and smaller).
It can use the same styles, but doesn't need nearly as much layout work. So I
don't think it should be a design goal to let you, say, produce this "current
(non-historic) status page" from the output of Waterfall by just switching
stylesheets or something.

Oh, also, it probably goes without saying that the CSS stuff is just for
visual presentation. If an application wants to programmatically get build
results, there are much much better interfaces to use than scraping the HTML
Even though scraping CSS-annotated HTML is easier, it's still wrong :).

> If people think augmenting the current HTML with these classes, I'd be 
> willing to submit the necessary patches.

I would greatly appreciate those patches!

FYI, The adapters in buildbot/status/html.py are used to abstract out the
differences between, say, a Change (which, on the waterfall display, gets put
in a box the "Commits" column), a BuildStep (which goes in a box in one of
the builder's columns), and an Event (like "connected", which also goes in
the builder's column). The "interface" for these boxes is IBox, and basically
the Waterfall code just adapts whatever the box's contents are to IBox, then
tells the resulting adapter to .getBox(), which returns an object that can
provide the HTML for a table cell through its .td() method.

Each Interface thus represents a region of the Waterfall display, and there
is an adapter for each useful (region, source-object) pair.

In this case, using Adapters wasn't really necessary (because we know all the
classes that can appear.. we need some kind of adaptation to take place, but
it doesn't have to be as flexible as what twisted's Adapter framework
provides). It did help to get all the HTML code out of, say, changes.Changes,
and into html.py where it belongs.

I'd be happy to walk you through the way html.py works if you want. It'll
take me a couple hours to remember it myself, though :).

thanks,
 -Brian