Before I get to my journey into the world of development, I wanted to briefly write about open source software and the collaboration therein that makes it all work. This particular post has been inspired by some issues I ran into while setting up this particular site. Using the very excellent Pelican static site generator and the plethora of plugins and themes available, I was quickly able to get the site you see now up and running almost flawlessly.

Documentation

I feel strongly that first and foremost, source code should be readable enough that it’s evidently self-documenting. This means that in the absence of any other documentation, it should be obvious to the reader of the code what’s going on.

That said, no one wants to go hunting through the source any time they wish to use a piece of software, certainly not complex pieces of software. Show me a poorly documented app/lib or an app with none whatsoever and I’ll show you someone me-shaped looking elsewhere. Documentation is vital if you want people at large to use your application. I’ll touch on documentation more in future articles.

One thing I’ve greatly admired about the Python ecosystem is the quality of documentation. Indeed, considering that there are usually several libraries to choose from when it comes to accomplishing tasks, I’ll often base my choice on how clear and concise the docs are. There are other considerations of course including how well battle-tested a library is, particularly for production grade applications. Good documentation also encourages others to get involved in your project, which is the lifeblood of open source; little coincidence then that some of my favourite and widely popular Python libraries [1] have excellent documentation.

When It Goes Wrong

Software has bugs. This is a fact of software development; lots of things can be done of course to prevent them which will be covered as I go through the chronicle of my dive into development.

For the purposes of this article though, we can jump ahead to an early lesson I learned with open source software: We’re not just limited to running into an annoying bug, filing a report and then making it an SEP [2], we can actually do something about it.

Once I’d worked my way through the Pelican documentation, I wanted a certain look and feel for the site. I’ve never liked the default of GLARINGLY WHITE BACKGROUND for the vast majority of web pages; they’re fatiguing on your eyes and aren’t fun to read, at night especially. After trawling through the pelican-themes repository I happened upon pelican-bootstrap3, a feature rich theme that allows you to choose from the generously free Bootstrap theme selection Bootswatch as well as make use of any other Bootstrap based theme you might wish to use. I opted for the Slate theme as it ticked most of the boxes I was looking for.

Impressively, installation went without a hitch largely due to the effort put into the pelican-bootstrap3 README. I had a site that looked Good Enough and so I dived into the various extra features and plugins I could make use of.

One such feature that caught my attention was the Tipue Search Pelican plugin, that allows you to make use of the Tipue static site search jQuery plugin without any heavy lifting on your part to keep the site data up to date. Unfortunately, once enabled as per the documentation disaster struck: Nothing I searched for produced any results.

Debugging

After ruling out any PEBKAC [3] potential by double checking my configuration and using a completely bare Pelican setup with the default theme settings and Tipue enabled, I was at first very tempted to just go and find another theme I liked that also provided Tipue support. Curiosity got the better of me however, as it often does and so I decided to start digging.

The beauty of static sites is you can debug them entirely in your browser’s Developer Tools (hit F12 in your browser) and get an idea of what’s going on:

Firefox Developer Tools

I quickly noticed that I was receiving a 404 error on a json file called tipuesearch_content.json and saw that no such file was being created. Various attempts at blindly renaming the resulting files still left me with a broken search page. What now?

Fork It, Fix It

It was soon apparent that resolving this was going to need some changes to either the theme, the Tipue plugin, or both. I therefore forked the pelican-themes and pelican-plugins repos to my own Github account and off I went to read the Tipue documentation. From here I realised the tipue_plugin author had updated their code to reflect that the Tipue library no longer stored page content in JSON files, however the pelican-bootstrap3 theme had not kept up with this change; sadly pelican-bootstrap3 was still set up for use with Tipue 5.0 and we’re two major versions ahead of that now at time of writing.

For anyone looking for a TL;DR version, you can look at the Pull Request.

In the end, the steps turned out to be pretty simple:

  1. Upgrade the in-theme jQuery to 3.3.1
  2. Upgrade the in-theme Tipue to 7.0
  3. Fix the search.html template so that Tipue was called correctly when the page renders:
@@ -8,16 +8,15 @@
  {% if 'assets' in PLUGINS %}
  {% include 'includes/minify_tipuesearch.html' with context %}
  {% else %}
+ <script src="{{ SITEURL }}/tipuesearch_content.js"></script>
  <script type="text/javascript" src="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/tipuesearch/tipuesearch_set.js"></script>
  <script type="text/javascript" src="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/tipuesearch/tipuesearch.min.js"></script>
  {% endif %}
  <script>
  $(document).ready(function() {
    $('#tipue_search_input').tipuesearch({
-     'mode' : 'json',
      'show': 10,
-     'newWindow': false,
-     'contentLocation': 'tipuesearch_content.json'
+     'newWindow': false
  });

That’s it! All that was required was updating the Tipue library, changing two lines in the base template and updating jQuery. Hopefully my pull request will be accepted!

Lessons

This is a great yet simple example of the power of open source software. Had Pelican, the pelican-bootstrap3 theme or the Tipue library/plugin been closed source, I’d probably still be twiddling my thumbs on a bug report somewhere. However, because I had all of the source code at my fingertips, good documentation and a little time to spare, I was able to not only resolve this problem for my site but also for others via a pull request to the Pelican maintainers. No duplication of effort; simply solve the problem for myself and then share the solution back to the community at large.

[1]Click, Pelican Docs, Requests
[2]Somebody Else’s Problem
[3]Problem Exists Between Keyboard And Chair