Review of Lightweight Documentation Systems for GetPoplog - GetPoplog/Seed GitHub Wiki

Lightweight documentation systems strive to allow developers to document their code and products in readable, plain text with relatively unobtrusive decoration to guide styling and structuring. There are the following considerations:

  1. What is the markup language? How is the language kept simple whilst making it capable of more advanced styling?
  2. What out-of-the-box themes are available and suitable?
  3. How are pages rendered for interactive review?
  4. How does a git push trigger a deployment?
  5. Where are the pages hosted?

We are currently using Jekyll on GitHub pages with a read-the-docs. The shortcoming that triggered this review was a lack of control over the auto-generated sidebar. A subsequent check showed that the sort order was controllable through the YAML 'frontmatter'. e.g.

---
sort: 2
---

I reviewed a series of alternatives - ReadTheDocs, Docusaurus, MkDocs and Sphinx. The summary was that the first three of them had some surprisingly unpleasant quality that made them hard to live with and by the time I got to Sphinx I had figured out a way of using Jekyll. Here's a brief summary of my findings.

ReadTheDocs

ReadTheDocs has become ad-driven. Adverts are an unacceptable distraction - and they look hideous. You can get rid of the ads for readers for a modest fee ($50/annum). Unfortunately we're looking for a decentralised solution and having to pay a license fee means someone having to always be there. It's not the money it's the organisational hassle.

Docusaurus

Docusaurus looks pretty nifty. But it fails to install on Ubuntu 20.04 because it has Node 10 and Docusaurus needs Node 12. And that's completely antithetical to GetPoplog. We're all about making stuff available using standard tooling. Software development is not supposed to be about solving the crazy maze of package installers. There's nothing in Docusaurus that really demands anything recent. They are just not people who think like us.

MkDocs

MkDocs is pretty. But the first time I tried to add a centred image I ran into link trouble because although the image was in the same folder as the page that referenced it, you need a '../' page because of MkDocs mapping. Frankly the inability to handle link mapping is why I dislike Markdown based systems. Now this might not sound much but it meant that we would be locked into MkDocs. That's unacceptable.

Sphinx

Sphinx is a neat system that I used for many years. With the Myst Parser it may well have proven viable https://www.sphinx-doc.org/en/master/usage/markdown.html. However it would have left us with a problem with regard to where we pushed the published documentation. As we had a complete working solution with GitHub Pages by this point, I stopped investigating it.