Development update – March 9, 2021

Website

It’s still a work in progress, but I’ve spent several hours working on two big improvements for this website:

  1. Dark mode 😍🌚

    Everytime I go to our website at night, it burns my eyes 😵 As a developer, I know how important a dark mode is, and I’ve tried different techniques to set it up here. To avoid FOIT – Flash Of Incorrect Theme – (see CSS-Tricks' Complete Guide to Dark Mode on the Web), I decided to go for the pure CSS at Operating System level version. Unfortunately, we’re using Bootstrap, which doesn’t support Dark Mode. After a lot of tries with Bootstrap, and after trying alternatives such as Halfmoon, I haven’t been able to have a good balance of simplicity and dark mode support.

    Since we’re still very busy developing our core business logic, I decided to stick with Bootstrap, to avoid rewriting a whole CSS theme for the website, but using SCSS variables overrides to handle dark mode. I’ve had problems, but it’s on its way.

  2. Tags 🏷

    We don’t have a lot of articles for now, but it still needs tags to organize subjects. Hugo provides very useful tools for tag organization, so it wasn’t very difficult. It’s almost done, but I’ll ship it with the Dark Mode support.

GitHub Pages redirection

Very simple task, but I just configured GitHub Pages to redirect monkiprojects.github.io to docs.monkiprojects.com.

This part is more aimed at developers. You can try to read it if you’re not a developer, but I don’t promise that you will understand 🙃

OpenAPI specifications

I’ve spent quite a lot of time improving the OpenAPI definition process and automating most of it. So far, here is my to-do list:

Monki Projects API improvements

In addition to developping most of the features defined in Monki Projects' API specification, I’ve configured SwiftLint, to enforce code style and conventions, and Sitrep, to analyse source code.

I’ve also spent a lot of time on a nasty Swift Package Manager bug… which was caused by a patch I wrote a few months ago 🤦🏻‍♂️

Automatic API clients generation

Monki Projects APIs are, for the most part, our business logic. Our apps and pieces of software are, for the most part, our business logic too. However, the communication in between is not. That’s why we decided to define clear OpenAPI specifications for all our APIs and automate client code generation in all languages. For now, we only support Swift (because no use case need another language for now), but it would be very easy to generate clients in tons of other languages (as long as they’re supported by OpenAPI Generator).

The Swift client generator is still in development, so its output is not as good as we’d like it to be (see OpenAPITools/openapi-generator#8901), but we’ll use it for now to save time, and will contribute later if needed.

Reusable SwiftUI views

We’re developping an app, on iOS for now (don’t worry, Android will come shortly after, that’s why I spend so much effort in separating and specifying everything), but there will be a macOS and iPadOS app too. Therefore, we need reusable views to make development faster and to have a great app identity. It will also facilitate code maintenance, readability, and will allow everyone to use Monki Map views (and all of Monki Projects' ones by extension) in their projects.

I’ve spent a lot of time setting up the architecture and automation mentioned above, so the app development had to be paused. However, I’ve created a small macOS app in a few hours – see the strength of having compartmentalized code? – allowing one to create an account, log in, log out, see users list and published/submitted places list. It was just a small project to test the infrastructure (successfully) and find problems (successfully too 😭), that’s why it’s not on GitHub yet.

Automatic diagrams generation

I’m a visual guy, and I feel these articles miss diagrams and pictures. To make it easier, I’ve decided to script the use of Kroki to generate diagrams from their textual descriptions. It has the advantage of allowing version control (using git) and has an incredible portability (since it uses Open-Source tools with common formats).