While reviewing comments on phpMyAdmin wiki (which we're shrinking down to developer documentation and moving end user documentation to proper documentation) I've noticed that people complained there on broken links in our documentation. Indeed there was quite some of them as this is something nobody really checks. It seems like obvious task to automate.
It seemed to me as obvious as somebody had to do it already. Unfortunately I have not found much, but at least there was Using Jenkins to parse sphinx warnings. This helps with the build warnings, but unfortunately I found no integration for the linkcheck builder. Fortunately it's quite easy with the Jenkins Warnings plugin to write custom parsers and to parse linkcheck output as well.
The Sphinx output parser based on above link can be configured like:
Regular Expression:
^(.*):(\d+): \((.*)\) (.*)
Mapping Script:
import hudson.plugins.warnings.parser.Warning
String fileName = matcher.group(1)
String lineNumber = matcher.group(2)
String category = matcher.group(3)
String message = matcher.group(4)
return new Warning(fileName, Integer.parseInt(lineNumber), "sphinx", category, message);
Example Log Message:
Percona-Server-1.0.2-3.rst:67: (WARNING/2) Inline literal start-string without end-string.
The Sphinx linkcheck output is quite similar:
Regular Expression:
^(.*):(\d+): \[([^\]]*)\] (.*)
Mapping Script:
import hudson.plugins.warnings.parser.Warning
String fileName = matcher.group(1)
String lineNumber = matcher.group(2)
String category = matcher.group(3)
String message = matcher.group(4)
return new Warning(fileName, Integer.parseInt(lineNumber), "sphinx-linkcheck", category, message);
Example Log Message:
faq.rst:793: [broken] http://www.hardened-php.net/: <urlopen error [Errno -3] Temporary failure in name resolution>
All you need to do now is to enable these in your Jenkins project, let the Sphinx parse output and the Sphinx linkcheck one file generated by linkcheck (usually _build/linkcheck/output.txt). The result can be found on the phpMyAdmin CI server.
