It’s still a work in progress, but I’ve spent several hours working on two big improvements for this website:
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.
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
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 🙃
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:
- Define OpenAPI specifications for each API in dedicated files
- Clean and refactor OpenAPI specifications (make them more readable)
- Merge all OpenAPI specifications files in one single file
- Generate Swagger UI interface for merged OpenAPI definitions
- Generate Swagger UI interface for all OpenAPI definitions (merged and separated) using
Monki Projects API improvements
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).
- Use Kroki manually
- Script diagrams generation
- Add cache to avoid useless diagram generation
- Store file hashes (SHA-256)
- Clean cache from deleted input files hashes
- Detect deleted output files (even though input file hash is cached)
- Allow multiple format output (i.e. know that
diagram1.svgis generated but not
- Add cache cleaning in case something went wrong (
-foption to force generation)
- Write script usage documentation
- Allow generation outside of monki-projects-api-specs
githook / GitHub Action to automatically generate diagrams on
- Handle script parameters properly