ReST for the Wicked

Rolling back, but at least rolling

The sad state of software complexity on our laptops and workstations has to stop. So many package managers are half bred, half blind, stupid and/or dangerous. What we need is kind of a Cyber-Roomba®, without any dependencies, written in Assembler.

Let's pretend for a second that you came here to read about a rock or pop song of a certain title and as soon as you discovered that this article wasn't even about the famous bible phrase you'd turn away in anger and quickly click some other link, just to undo your impulse to come here for a small dose of infotainment –
Still here? ^^
Then let's ask: what would you have gained this way?

My point is that we are too quick too often, be it in our assumptions as in our verdicts, and the fact that it's ever so easy to click or tap doesn't really help us making educated decisions like, let's say in the real® world.

In my previous blog post here I wrote about how we improved our documentation with Sphinx and ReST and how for smaller projects MkDocs would be a valuable alternative.
And it is! But time has not stood still.
Within less than a year, with nearly no effort we're now able to deliver wonderful documentation to ReadTheDocs, including versioning, i18n and export to html, pdf and epub and it doesn't even matter if we used MarkDown or ReST any more. Cool.
But there's a little caveat: we still have to accept some shortcomings in each language.

ReadTheDocs eg. won't render hierarchic lists in MarkDown. There's only one bullet level, no matter how much you're nesting.
MarkDown also doesn't know indentations at the line beginnings, which is not unimportant when dealing with poetry. (Unelegant solution).

On the other hand, writing texts with simple short sentences and many new lines (like for childrens' books) in ReST is also still a PITA.
You'll sure find many more problems while digging.
But should these already be final arguments pro or con the one or the other??
I don't think so.
Of course staying on a course becomes frustrating if there are too many obstacles and sometimes you have to say No and just look somewhere else.
Then again, finding errors and then workarounds while still proposing solutions to the originating problem often seems much more viable to me, than running away lamenting and demanding.

To elaboate this, please let's change the subject for a moment, if you don't mind, and allow me to talk about a rather bitter observation I had made lately and how I came to terms with it.
It's about hacking my own working environment, a.k.a. the sad state of software order and control over our dear laptops or workstations.

Just like everybody else long long ago I had at some point needed a newer version of Apache. Or MySQL. Then PHP. Then Python. And so on.
First the only solution to this were MacPorts. Then came HomeBrew. Then easy_install, pear/pecl, cpan, npm, composer, just to name a few. Even Docker.
And while every tool in itself was totally reasonable and perhaps promising, after only a few years I ended up with a multitude of packaging systems on my Mac until I only wanted to scream WHAT'S WRONG WITH US, WHY CAN'T WE JUST HAVE NICE THINGS LIKE APT-GET!!! (which doesn't make much sense on OS X anyway, doesn't it …)

Window title says it all.

Bits in a Box

In comes the Raspberry Pi 2. But prior to its praise I have to give credit where credit's due: the BeagleBone Black with it's built-in Cloud9-IDE- and the handy USB-Auto-IP-Setup to was my very own eye opener.
Because somebody out there had simply figured out how it would be, if we could just work on this little thing by attaching (and powering it) from a laptop's USB port!
For nearly a year now I've been doing all my tinkery-hackery nearly exclusively on the Raspberry Pi 2. Even the MacBook seems happier. :)

Productive is the new orange ;)

Well, how, you might say, could such a preinstalled Cloud9 instance inspire me, I'm not a programmer, right?
And indeed, I'm totally not! But just like at the introduction I argued: going somewhere and then quickly running away, just because you encountered the unexpected or uncomforting is often the weak decision. A clean little machine that ran a state of the art OS and client/server software, was expandable and needed only a minimum setup was where I finally thought tinkering with software might become fun again!


For the last few weeks I have been working on it, even alternating with the new Ubuntu MATE desktop, and I must say I don't want to go back again, into the brew. ;)
I'm perfectly happy with OS X on the MacBook in its almost native state and even more so when I can be sure that security concerns besides the obvious ones - which fall into Apples duties - are a thing of the past for me.
My Ubuntu powered Raspberry Pi 2 however is where I can try and err.
If anything goes wrong, what I'd resort to in the absolute worst case would be a cleanly installed SD card with MATE, a setup that would take under 5 minutes and git.

Maybe this is something only an editor can achieve because of "text", I don't know. Maybe web developing still does need much more horsepower? But I doubt a little, because, hej, you're user 1 on a quad core CPU!
Anyway: delegating my tasks not into some cloud or container, but to a tiny, cheap and silent little friend in my flat instead has made my work much easier.

Look, Ma, I can haz updates!

But hey, that's not all, yet!! I also evaluated Nikola, Hugo and a few other static website generators that work with ReST lately and would like to share a few bits with you!
For instance how maybe it was about time to merge rather strict & dull documentation and shiny & inspirational web publication more and find new, better accessible and fun forms of bringing the spirit behind software to the people, so they actually might even enjoy the results! :)
– Oh, I see, we've run out of time, sorry, time for a rest. Then next time. Promised!

This article's motto was No Rest for the Wicked, anyway, wasn't it, and we'll change it to "Come for the documentation, stay for the web publishing" now and hopefully see you back again soon!

About the author: Rainer Schaupp

The master of staying power and many letters - be it detailed concept work or the most extensive project documentation we've ever seen. Will otherwise challenge us with detailed tests of our work.