Frustrated by Magento? Then you’ll love
Over the weekend I finished up phase 1 of my project to get better documentation around pestle, my home rolled command-line-framework/Magento 2 code generation tool. Four days ahead of schedule! I’ll be taking a small break to work on some other things, and then picking back with with the next phase, which is documenting pestle itself.
Read the Docs
This was my first time using the popular Read the Docs service to publish. Before starting, I has assumed Read the Docs offered some sort of technical docs taxonomy, and a web application for publishing in that format.
This isn’t quite the case. Read the Docs is more of a continuous integration/delivery system that supports two documentation formats — Spynx and MkDocs. Where things get blurry is is there’s a “Read the Docs” theme for Spynx and a Read the Docs theme for MkDocs. It’s not 100% who came up with this theme and who provides it for each documentation project.
Regardless of that, when you publish to Read the Docs, you’re just building documentation using the standard Spynx or MkDocs commands — the value Read the Docs provides is in the free hosting, and having done the leg work of setting up a GitHub integration you can hookup to projects, and a web application for managing everything.
Markdown, MkDocs, and highlight.js
I tried getting started with Spynx but it’s a robust system whose conventions weren’t obvious to me. When I discovered MkDocs was supported, and I could write using Markdown, I jumped ship quickly.
The Read the Docs theme for MkDocs felt a little underpowered compared to its Spynx counterpart, and I ran into a bit of trouble with the syntax highlighting. The Read the Docs MkDocs theme uses highlight.js for its documentation, and pulls the language from a string that immediately follows the first “fence” of a fenced code block.
I’m a bit of a markdown originalist and prefer the four-space-indentation style for code blocks. This would have been OK, except that highlight.js, (as implemented in the MkDocs Read the Docs theme), seems to automatically detect the language of your code blocks and applies syntax highlighting. It also automatically detects a language for things like “show the user expected shell output”, which meant a majority of my sample output was gently munged with unneeded colors and bold text.
I could have just gone through and manually changed all my indented code blocks to fenced code blocks, but I decided to see what the state of the art was in Markdown parsing. Putting the politics of the project aside, it seems like the CommonMark project resulted in a decent reference spec that’s allowed all sorts of parsers to pop-up, including one implemented in PHP.
After a few false starts (the “f” in final class stands for F——K Y—U) I managed to hack something together that could round trip my markdown, which in turn let me automatically convert my indented markdown into fenced markdown with a plaintext code-style designated. (That code’s over here if you’re interested, but it’s in a very laravel stage)
I thought I was done, but MkDocs/highlight.js were still trying to syntax highlight my code. Some sort of auto-detection was still injecting language classes into the generated HTML along side the plaintext class. I ended up writing some patchy CSS to work around this, and then backed away slowly given the tone of conversation
Finally — the Read the Docs theme/model itself was a bit of a challenge. There’s benefits to tying all your h2 element to navigation items, but it meant I needed to truncate the magento2: portion of the command names in order to make things fit. I might revisit Spynx to see if it’s more flexible in this regard.
Read the Docs is a great project, but it’s not quite what I thought it would be. i.e. there were still a lot of sharp edges to trip over and uneven ground to slice your fingers on.
Magento 2 and Pestle
It was interesting revisiting these commands after a bit of time away from Magento. I was surprised to find I had a command mis-categorized, which always gives you some “is anyone even using this” feels. I also had a bit of regret around not creating a tighter system for the “this file gets created, user gets notified about it” notifications. For example, the magento2:generate:ui:form command suffers in that it doesn’t tell you all the files it created, including the actual UI Component file itself, pulsestorm_pestle_things_form.xml. A feature for the future, perhaps.
I suspect I’ll have other pestle feeling when I get to the next milestone.
As for Magento 2 itself — a lot of “it didn’t have to be this way, but it’s not my project” feelings. Companies are spending a lot of time and effort trying to shift open-source projects towards a commercial/free-labour model. Probably best to just stay out of their way unless you want to end up a bug on windshield of late-stage capitalism.