Bug 1012224

The rationale for offering this feature is that any given Beaker instance is going to want to provide instance specific URLs for:

- information on who maintains the instance and how to contact them
- instance specific architecture guides (where the labs are, etc)
- instance specific help guides (e.g. repos for additional client workflows, additional proprietary support libraries for writing tests, version control information for test development)
- instance specific live metrics and data mining resources (Reports->External covers a little bit of that, but isn't very discoverable)

Rather than providing an "add custom links here" feature, it makes more sense to just make it possible to customise the overall site template that defines the main navigation bar.

Installations may also want to configure the look-and-feel of the application to provide a better fit with a larger suite of test tools rather than using the generic settings provided by the upstream project.

Currently the base layout for every page comes from master.kid, using Kid's template inheritance features (py:extends and py:match). It provides the menu structure, Log in button, bug link footer, and other such things.

Kid is basically dead these days, its web site is no longer reachable, but you can read the docs on web.archive.org:

http://web.archive.org/web/20090404035343/http://www.kid-templating.org/language.html

For this feature, the simplest implementation would be to allow the administrator to set a config option in /etc/beaker/server.cfg pointing at an alternative master.kid template, which all the Beaker templates inherit from. Or else we could define a new directory /etc/beaker/web-ui-templates/ which is added to the template search path, so that the administrator can put a custom master.kid in that directory and override the standard one. (I'm not sure if this latter idea is possible with TurboGears, would need to figure that out.) Either way, the administrator would then have to copy the standard master.kid and add their customizations. They would have to keep their custom version in sync with the standard master.kid in future.

A nicer, but more difficult, implementation would be to use py:match/py:extends functionality in master.kid so that the administrator can hook in extra elements inside or around the existing master.kid layout, without needing to copy all the stuff that is in there.

The Kid stuff turned out to be the easiest part, since TurboGears already has a mechanism which can be used for this (tg.sitetemplate). The hard part was building CSS at runtime instead of build time, so that admins can supply an additional site-specific Less source file.

Move help links out of the footer into a new top menu (the motivation here is so that themes can add extra links to the menu):
http://gerrit.beaker-project.org/3054

Inject TurboGears JS and CSS in master.kid so that site templates don't need to repeat the same injection stuff:
http://gerrit.beaker-project.org/3055

Build assets at runtime:
http://gerrit.beaker-project.org/3056

Define site.less as a symlink which admins can adjust to point at their custom site-specific styles:
http://gerrit.beaker-project.org/3057

Docs describing how to theme Beaker using these mechanisms:
http://gerrit.beaker-project.org/3058

Beaker 0.17.0 has been released.