Segway

... so yeah. I needed to add a static page, and I had a bunch of ideas about extra stuff I wanted to do for a while. But mostly, I just needed to add a damn static page, and thinking about coercing the existing setup into doing that with all the pictures I needed there was not making me happy...

... it was also about time I set this thing up so that I could actually log more projects than just a single airplane. Hey, I bet we all know - websites of this kind are mostly created to be later enjoyed by their authors in periods of 'I ain't got nothing better to do than review my old notes' mood ...

Multiple Projects

First of all, I wanted to be able to log multiple projects. The way the old setup was done was it had basically one project, under the section called "Build", and then this dangling catch-all "blog" thing for everything else.

But as you can see, most of articles here actually are NOT about the airplane I was working on at the time - the Skybolt - but rather, other little things here and there.

First thing I did, is I changed the way the files are laid out, and added semantics converting source content's directory structure to "Project / Section" semantics.

Each project now has it's own "sub-log" (that's what time logged is tracked based on). There is still a catch-all "blog" section, and a "default" project that can be configured if one so desires.

Logging

One more thing I realised is that the original version would only allow to log time if it was associated with an article-type entry... Flooding the Internet with tens of pages of "built three more ribs tonight" type stuff just to log time seemed kinda silly, so I added support for plain text log entries.

Articles still can track time; but you can also now have a separate text file with just "Date", "Summary", and "Time Logged" entries - one per line.

When creating the "log" page for a project, entries, being both from articles and from logfiles, are sorted by date, and then ones with articles associated with them will pick their summaries up from articles. Entries coming from text files will be displayed with summaries from log files.

Major Code Cleanup

All this time tracking functionality, structuring articles into projects, and such, were becoming an entity of its own large enough for me to justify clumping it all into a single Pelican's plugin, now called "b_log". I also added a bunch of config options to set up it's behavior.

No Google Analytics

Yeah. I killed it. This site Does Not Track You now. Because there's too much of this crap online.

Fixes, Fixes, Fixes

Too many to count...

• Fixed how logos and icons behave
• Fixed templates in numerous places
• Fixed bugs in image processing and copying
• Images in pages now handled properly - they just weren't. At all
• Decimals in logged times would sometimes show up to 10 digits past the decimal point
• ...

Silliness

And finally, some silliness! I wrote another plugin that adds a "quote of the day" at the end of each article, randomly :) Enjoy; and I hope they will encourage you to read more articles (or at least, scroll thru them to get to the bits of wisdom).

And So, (v2)

I got happier now.

I have changed the B-Log notes to match the new setup, just so that there's one place I can send people to in case they are interested in my setup.

And I'm very close to posting that damn page, but...

...of course, I am restructuring the old content and modifying old pages instead to match what I got now, and writing stupid notes on what I did to the thing. Because, as we all know, making yourself a tool is as, if not more, pleasant, as using it...

The Problem

... was that I needed something to organize my builder's log. Being a software engineer by trade, I didn't want to go old school with paper logs and pictures, and whatever-random-collection-of-stuff-on-a-computer I could do. I wanted something that's easy to add entries to, calculates everything automatically, and allows me to publish it on the Web. Plus, I find it pleasant to view HTML as opposed to .doc, .pdf, or whatever.

Being a nerd, I just had to make it as nice for myself as I could...

The KitLog Pro

Many-a-builder is using this apparently successful piece of work. Apparently, as of writing this, they have over 1100 logs published on their mykitlog.com.

I have played around with it quite a bit. The program is trivially simple; but I can't stand the way it's architected.

• Windows only
• Uses Access database for storage (sic!!)
• Only three pictures per entry (really???)

Oh, the Access databases. Basically, what this means to me as a user is if it ever .. erm.. decides to stop working, I will loose all my data. "Revert to a backup", you say.. Yes, but if the problem is that I can't add my N+1st record because the DB just corrupted itself, no backup will help -- I'm stuck.

On top of that if, god forbid, KitLog ever goes out of business, I am stuck with the data that I can't export w/o some serious reverse engineering.

No thank you. :)

The Early Attempts

So, I was toying around with other stuff.

Mutilation of the Pelican

The Pelican. I fell in love with this thing almost immediately. Here's what it does:

• Takes a directory with a bunch of ReST, Markdown, or ASCIIDOC
• Parses all those files into internal state, obtaining metadata from both files and paths (ie, if you organize your files in category/<date>/name way, you can tell it to properly parse that path and populate the metadata)
• Uses Jinja templates for generating a bunch of HTML output
• Allows plugins and custom templates
• Is all Python!

I did the initial version in 2014 (the date of this article). Then, I've spent about a week tearing it to pieces and figuring out how it works, and adding a few plugins to add things that I needed for the B-Log that it didn't have. I added time tracking, changed layout, got a Bootstrap-based template and modified it, etc.

In 2018, I fixed some suff and added a few more things.

You be the judge of results :).

Here's what I've done, in the end:

• I'm writing text in ReST, so I've added the custom directive to it allowing for 'figures'. Problem is, ReST image directive produces HTML that wasn't much useful to present images the way I wanted them. Instead of modifying core Pelican code, I elected to add a custom 'Figure' directive. This is done as a Pelican plugin. This plugin also automatically adds thumbnails for images. This is the figure_process plugin. It also requires the image_copy plugin.
• Another plugin I've written is image_copy. It enables sane handling of images placed next to the entries (pages and articles). Back when I started in 2014, Pelican wanted you to separate images and text (and it's internal mechanism of not separating them was broken back then). Pelican guys might've fixed this in the last 3 years, but hey, my setup worked for me - and I kept it.
• And most importantly, the plugin that allows the bulk of functionality - the b_log plugin. It does a lot of stuff:
  • Generates the project structure ("Project / Section" concept with multiple projects)
  • Enables a special metadata tag to track time in an article
  • Loads and parses logfiles that don't have articles associated with entries
  • Calculates totals
  • Creates internal data structures for theme templates to use
  • Renders log pages
• Then came theming. Pelican is geared towards bloggers, so I had to tweak a lot of things to be better suited for B-Logging (build logging, remember? :) ). In the process, I've switched to Bootstrap, since it makes it very easy to organize content on a webpage. I added theme templates to produce the build logs with totals, etc, etc. Also integrated FancyBox - a really cool JavaScript image overlay.
• I added a couple of extras for myself - like silly QuOTD messages at the bottom of each entry - but that's not strictly related to B-Logging...

I like the end-result. I enjoyed hacking at it, and this was the first time I touched Python (so had to learn that on the way). Pretty neat (though I still prefer Perl (now, why do you need lists and tuples and sets again? :) ).

The only drawback is that it's regenerating everything every time. You can easily see how that might become a problem when you get a lot of entries, but I'm feeling like I'm ways away. 30 pages take about a second. I think I will need a lot of records before this becomes a problem; and at that point I will rewrite the whole damn thing to cache stuff.. probably :)

The code is here. The repo includes my theme, plugins, some tools, and sample content. It requires Python (I used 3.6 and did not test anything else), Pelican (which is checked into the repo in pelican/, along with it's dependencies), and Pillow (pip install pillow). Oh yeah, and pelicanconf.py's PATH_METADATA will likely require tweaking of slashes on Windows.

Read the config file (pelicanconf.py); and read thru Pelican docs to get the idea. sample-content/ contains my sample generated content that I was testing with. content-gen/ contains the simple Perl script that generates as much sample content as you want.

/project-one/section-one/

        2001-01-01-entry-one/
                    entry-one.rst
                    picture.jpg

        section-one-log.log

/project-one/section-two/

        2001-01-02-entry-two/
                    entry-two.rst
                    picture.jpg

        section-two-log.log

/project-two/section-one/

        2002-01-01-entry-one/
                    entry-one.rst
                    picture.jpg

/project-two/section-two/

        2002-01-02-entry-two/
                    entry-two.rst
                    picture.jpg

2011-01-01 | Some Summary Here       | 1.02
2011-01-02 | Some Other Summary Here | 2.02

And So,

I am very happy with this so far. I have all my logs in practically plain text format, parser for which is open source and available. I have it nicely organized, and I can back it up as I please (to GitHub, anyone? :) ). I can re-write the programs that parse and produce final .html. I can extend the generator and change the theme to produce a printable version of the log, styled for paper rather than web. The list goes on!