I’ve just released the 40.alpha release of yelp-tools, the collection of tools for building and maintaining your documentation in GNOME. This is the first release using the new Meson build system. More importantly, it’s the first release since I ported the tools from shell scripts to Python.
Porting to Python is a pretty big deal, and it comes with more improvements than you might expect. It fixes a number of issues that are just difficult to do right in a shell script, and it’s significantly faster. For some commands, it can be as much as 20 times faster.
But that’s not all. You can now provide a config file with default values for all command-line arguments. This is useful, for example, with the --version option for yelp-check status. Previously, to ensure you weren’t getting stale status information, everybody had to remember to pass --version. Now, you can set the current version in your config file, and it will always do the right thing for everybody.
It gets better. The config file can specify custom checkers for yelp-check. I blogged about custom checkers a couple months ago. You can use XPath expressions to make assertions about a document. This is very similar to how Schematron works. But now you don’t have to figure out how to write a Schematron file, call xmllint with it, and parse the output.
Here’s an example of how to ensure that every page uses XInclude to include a boilerplate legal.xml file:
[namespaces] mal = http://projectmallard.org/1.0/ xi = http://www.w3.org/2001/XInclude [check:gnome-info-legal-xi] select = /mal:page/mal:info assert = xi:include[@href='legal.xml'] message = Must include legal.xml xinclude = false
To run this check, you simply call:
yelp-check gnome-info-legal-xi
For more examples, check out the config file I already added to gnome-user-docs.
What I’d like to do now is figure out a good way to share custom checkers across modules, and then add CI pipelines to all GNOME modules with user docs to ensure consistency.
