Fighting with Pelican

Posted on Thu 04 August 2022 in MUPS16

Whilst trying to write up some work I've been doing on the control unit I ran into a problem: when building the web pages I wasn't getting overbars on control signals (e.g. THIS). I had a vague memory of having solved this a couple of years ago when I first started documenting the project, but I must have solved it in Pelican somehow without committing it (stupidly), and when my old machine died I lost the changes. Since it took me a while to get things working again, I thought I may as well write it out now.

Overbar

I'd previously solved this by adding a role called overbar, which can be added to any intepreted text (text inside single ` characters) to add an overbar. Adding the role is simple: just add

.. role:: overbar(literal)

somewhere in each .rst file that needs overbars. This can then be used as

the active-low control signal :overbar:`HALT` triggers

Unfortunately, this doesn't work out of the box. All it does is add an overbar CSS class to the span, alongside the existing literal one that makes the text fixed-pitch. To actually add the overbar we need to change the CSS to add the definition:

.literal {
    text-decoration: overline;
}

Since I'm using a customised version of the Flex theme for Pelican anyway (to add a preview image for posts with image galleries) I just made this change in static/stylesheet/style.less.

This almost worked. Unfortunately, by default the Flex theme uses a minified CSS style sheet, and I haven't bothered to get tools for minifying CSS set up, so I had to add

USE_LESS = True

in pelicanconf.py so that the non-minified version is used.

Tables

As an aside, I noticed that the tables generated from .rst files looked different from those generated from .md files, which was surprising. It seems that Restructured Text generates all tables with a hard-coded border="1" attribute in the <table> tag, which, for the Flex theme at least, leaves thin black borders where there shouldn't be any. It also doesn't seem that there's any way to either prevent the attribute being added, or completely override it in the CSS. Adding

table {
    border: none !important;

to the stylesheet doesn't work, since the table still gets a single-pixel border, though it somehow changes colour, and the maintainers of Docutils seem resistent to removing the hard-coded border. I think I'll just resort to a hack and put a post-processing step in the makefile for the project that seds out the border="1" in table tags before uploading.

website