Skip to content

RFC: docs: generate features.html from features-{api}.yml

Erik Faye-Lund requested to merge kusma/mesa:docs-features-yml into main

Ever since we've switched to using Sphinx for the docs, features.txt has annoyed me a bit.

The idea of embedding the information from features.txt into our HTML documentation seems good to me.

Sure, mesamatrix.net already does this (and more), but I think it's a bit nicer to have a light-weight version in our docs. Besides, what mesamatrix does in addition is IMO a bit more opinionated, my tracking "top drivers" by numbers of extensions etc.

So here's my proposal; structure the data into some YAML-files that we parse and generate RST-sections with tables, using a bespoke Sphinx extension.

One obvious problem whenever we change how we store this information is that mesamatrix parses our features.txt-file. But hopefully, structuring it all as YAML makes this job easier for them going forward. These files seems both easy to edit and to parse, so maybe it's a win-win?

One kinda-downside here is that I only bothered to structure the data enough to generate these tables; the status-strings are entirely text, for instance. For mesamatrix.net, this means they'll still need to parse a bit of data. This could of course be changed, but I think I'd like to hear some input before I spend time on that.

In either case, I don't propose merging this as-is. This is just to get some comments, because I'm unsure if this is the right direction or not.

Merge request reports