Skip to content

Modernize Spec Website Generation

Matthias Klumpp requested to merge wip/mak/site-refresh into master

Hi!

This very large MR modernizes the specification generation for our DocBook specifications using openSUSE's DAPS tool. It also converts a few random textfiles and raw HTML files into DocBook to make things a bit easier to maintain for me (as having just a few formats is much nicer than having to cope with a whole zoo - long term we can probably add something like AsciiDoc or some Markdown flavour as well).

The specification registry is now a TOML document, and it should now be very obvious which file ends up where and why just by looking at the data.

I aimed for a reasonable amount of backwards-compatibility, after I found out that keeping 100% of the old links working was infeasible due to how the newer tools handle certain filenames. Symlinks and redirects are in place for the most common pages, and I will add more as I find new cases where redirects are needed. We also currently generate fewer doc variants, which is hopefully okay (let's see!).

This patchset will also get this repository off Python2 and some odd DocBook hacks, and overall will hopefully reduce the maintenance burden in the long run and also make it more pleasant for new contributors to propose changes, as local validation of documents is now also easier.

I get that this MR is basically un-reviewable due to the sheer volume of changes and churn (if you want to look into it, please do though!). So as an easier way to look at the changes, I uploaded the generated HTML here so you can check if anything looks odd: https://people.freedesktop.org/~mak/tmp_fdo-specs-refresh/

Feedback is very welcome!

Merge request reports