CI linter/sniffer for documentation repos

[email protected] (Jordi Kroon) Sat, 25 Apr 2026 19:59:47 +0200
Newsgroups php.doc
Message-ID <[email protected]>
In order to improve consistency and reduce review overhead in DocBook 
contributions thus helping both contributors and maintainers, I’ve been 
working on a linter/sniffer project called Docbook CS over the past few 
weeks.

You can find the project here:
https://github.com/jordikroon/docbook-cs

And a sample implementation targeting the doc-en repo here:
https://github.com/php/doc-en/pull/5510

In the files changed tab you can see in-line failures that were detected 
by the sniffer.

At the moment, it includes a few focused checks, but is easily possible 
to add or alter sniffs as desired.

For example:
  - Ensuring that when an element has both xml and xmlns attributes or 
xmlns variants, xml appears first
  - Exception or error class names wrapped in <classname> that should 
use <exceptionname> instead.
  - Cases where <simpara> should be used instead of <para>

It can run against the entire doc project or just a subset, such as a 
git diff, which makes it suitable for both local development and 
automated checks. It should also be straightforward to use this for 
other language repositories such as doc-fr.

I’d be interested to hear your thoughts. If it seems useful, perhaps we 
can add this to the workflow or find another way.

Happy to iterate based on feedback.

Regards,
Jordi