ci: Enable fail on htmlcheck error

[hdiethelm]

Now that #4410 got merged: Should we fail the CI if any new issue is introduced?

It also makes more sense to check for a clean repo after htmlcheck and fixed some spelling.

[hdiethelm]

Hmm, interestingly, when I build the doc locally, I have some errors:

List of broken links and other issues:
file:///home/hannes/linuxcnc-src/docs/build/html/de/gcode/overview.html	
 Lines: 37, 336
  Code: 200 (no message)
 To do: Some of the links to this resource point to broken URI fragments
	(such as index.html#fragment).
The following fragments need to be fixed:
	sec:%C3%9Cbersicht-Parameter  	Line: 336

However, in CI, there are none. If I check https://linuxcnc.org/docs/devel/html/de/gcode/overview.html, this paragraph is not translated:

Locally, it is:

and the link is UTF and broken:
overview.html#sec:%C3%9Cbersicht-Parameter

I also checked the CI artifact, this paragraph is not translated. Looks like some tool in the CI behaves differently than in debian trixie.

[hdiethelm]

Indeed:
docs/po/de.po

#. type: Plain text
#: src/gcode/overview.adoc:157
msgid ""
"Parameters are identified with a \"#\" symbol in front of them. See "
"<<sec:overview-parameters,Parameters Section>> below."
msgstr ""
"Parameter werden mit einem \"#\"-Symbol vor ihnen identifiziert. Siehe den "
"<<sec:Übersicht-Parameter,Abschnitt zu Parametern>>."

Original HTML is mostly identical:

--- linuxcnc-doc-local/html/en/gcode/overview.html	2026-08-25 23:34:01.435799957 +0200
+++ linuxcnc-doc-ci/html/en/gcode/overview.html	2026-08-25 23:17:06.000000000 +0200
@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 2.0.23">
+<meta name="generator" content="Asciidoctor 2.0.20">
 <title>Overview of G-Code Programming</title>
 <link rel="stylesheet" href="../../asciidoctor.css">
 <link rel="stylesheet" href="../../rouge-github.css">
@@ -2544,7 +2544,7 @@
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2026-08-03 22:24:04 +0200
+Last updated 2026-08-25 20:58:41 UTC
 </div>
 </div>
 </body>

Translated HTML is different:

--- linuxcnc-doc-local/html/de/gcode/overview.html	2026-08-25 23:34:00.359765795 +0200
+++ linuxcnc-doc-ci/html/de/gcode/overview.html	2026-08-25 23:17:10.000000000 +0200
@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 2.0.23">
+<meta name="generator" content="Asciidoctor 2.0.20">
 <title>Überblick zur G-Code Programmierung</title>
 <link rel="stylesheet" href="../../asciidoctor.css">
 <link rel="stylesheet" href="../../rouge-github.css">
...
@@ -333,13 +333,13 @@
 <div class="sect3">
 <h4 id="_parameter">2.3.2. Parameter</h4>
 <div class="paragraph">
-<p>Parameter werden mit einem "#"-Symbol vor ihnen identifiziert. Siehe den <a href="#sec:Übersicht-Parameter">Abschnitt zu Parametern</a>.</p>
+<p> Parameters are identified with a "#" symbol in front of them. See <a href="#sec:overview-parameters">Parameters Section</a> below.</p>
 </div>
 </div>
 <div class="sect3">
 <h4 id="_unterprogramm_codes">2.3.3. Unterprogramm Codes</h4>
 <div class="paragraph">
-<p>Auch als "o-Codes" bezeichnet, werden diese Programm-Kontrollfluss Kommandos (wie z.B. if-else logic und aufrufbare Unterprogramme (engl. callable subroutines)) angeboten und auf der Seite zu <a href="o-code.html#cha:o-codes">o-Codes</a> und auch unten im Abschnitt <a href="#sub:subroutine-parameters">Subroutine-Codes und Parameter</a> beschrieben.</p>
+<p> Also called <em>o-codes</em> these provide program flow control (such as if-else logic and callable subroutines) and are covered fully at the page on <a href="o-code.html#cha:o-codes">o-Codes</a> and also below in <a href="#sub:subroutine-parameters">Subroutine Codes and Parameters</a>.</p>
 </div>
 <div class="admonitionblock note">
 <table>
...

... and much more untranslated parts...

[BsAtHome]

The actual translation is done with po4a. Asciidoctor compiles .adoc into .html.

[grandixximo]

And the translations come from weblate, we will never be able to enforce these. It's an ongoing battle, no new push comes trough till one is merged, like the latest weblate PR #4466, it introduces a warning, I fixed in weblate already, but we must merge it for the fix to come trough, if we were to enforce, everything will be broken after merge.

[hdiethelm]

The actual translation is done with po4a. Asciidoctor compiles .adoc into .html.

So the process is (probably oversimplified):
Weblate -> PR > docs/po/
doc/src/*.adoc -> docs/build/adoc/en/*.adoc -> po4a -> docs/build/adoc/LANG/*.adoc -> asciidoctor -> html

Looks like there is an issue in CI with the adoc translation. My last commit uploads the full doc/build folder as a second artifact and indeed, there are many not translated parts in the adoc files generated in CI while the locally built parts are translated.

And the translations come from weblate, we will never be able to enforce these. It's an ongoing battle, no new push comes trough till one is merged, like the latest weblate PR #4466, it introduces a warning, I fixed in weblate already, but we must merge it for the fix to come trough, if we were to enforce, everything will be broken after merge.

So that means only after merge, a new PR is created? Is it not possible to drop a PR, fix it in weblate and create a new one? In that case, a failing CI would indeed be annoying. So I will just (miss) use this PR to instigate the translation issue.

[grandixximo]

I never thought about closing the PR, maybe we'll get a new one, let's try...

Usually weblate comes once a week or so, so probably will have to wait a while to know if closing spurs another PR, if by next week I see no new PR, I'll reopen and merge, we'll see

[hdiethelm]

Some investigation later:
This command: po4a --msgmerge-opt='-v' --no-update po4a.cfg is basically all that does the translation right?
Ubuntu 24.04: po4a 0.69-1
Debian Trixie: po4a 0.73-2

Let's test something, github now supports ubuntu 26.04 which has po4a 0.73-2...

[hdiethelm]

I never thought about closing the PR, maybe we'll get a new one, let's try...

Usually weblate comes once a week or so, so probably will have to wait a while to know if closing spurs another PR, if by next week I see no new PR, I'll reopen and merge, we'll see

Let's see, hope nothing breaks... ;-)

[hdiethelm]

Indeed, switching CI form Ubuntu 24.04 to 26.04 solves the translation issues.

Differences Trixie to CI 24.04, there are many non translated parts in CI which are translated in trixie while the en version is equal, except the missing links:
diff_ci_en_24.04.patch
diff_ci_de_24.04.patch

Differences Trixie to CI 26.04, the result is virtually the same. htmlcheck.sh shows the same issues locally than in CI.
diff_ci_en_26.04.patch
diff_ci_de_26.04.patch

However, I wonder why the a few links are gone in CI? Same with 24.04. Might be this needs also investigation. Might be something is missing, so these are not built in CI?

Options:

1. Stay at 24.04 and get a new version of po4a
2. Change only the doc stage to 26.04
3. Figure out the underlying issue and try to get it working with po4a 0.69-1
4. Change all working stages to 26.04 while leaving the failing jobs at 24.04
5. Change all stages to 26.04 and fix the issues (4 jobs fail right now)
6. Go to all in docker and use debian trixie (Ideally with pre-built docker images, I have a prototype running since some time)

I would go to 2., might be 4. and create an issue to fix the other 4 jobs later. Any opinions?

Only downside: 26.04 is still preview, could result in fixes needed in the future: https://github.com/actions/runner-images

[BsAtHome]

The problems are real issues. Has anyone ever tried to build and test on an actual Ubuntu 26.04 system?

The problems should be investigated and fixed. Especially the tests failures looks serious. The cppcheck are minor issues. The clang build seems to be missing a header or a link library.

Then when the CI platform come out of preview, then we can switch and already have working system.

[hdiethelm]

The problems are real issues. Has anyone ever tried to build and test on an actual Ubuntu 26.04 system?

The problems should be investigated and fixed. Especially the tests failures looks serious. The cppcheck are minor issues. The clang build seems to be missing a header or a link library.

Then when the CI platform come out of preview, then we can switch and already have working system.

Agreed, so it will be 5. then. I guess it makes sense to create a new PR that switches the CI image and fixes the issues.

• The cppcheck issues look like a new check got introduced, this can be either ignored or fixed. Most look easy fixable.
• clang needs now -latomic, then it should work.
• The failing tests look more demanding, something is wrong there. Often, it's undefined behavior that got changed in a new compiler. There are tools to check this, let's see, -fsanitize=address -fsanitize=undefined helped me a lot to debug a wired memory alignment issue in an other project.

[grandixximo]

I'll take a look at the weblate failures tomorrow, seems like a lot of broken links came up

[hdiethelm]

I have no Ubuntu but I can run full Linuxcnc in docker, this works quiet well to quickly check different OS's.

The failing tests are G70 / G71:
G70 Lathe finishing cycle
G71 G72 Lathe roughing cycles

I guess there are not used that often. I have a mill, so I can not check them on real hardware and I would have to read in what these even do.

[BsAtHome]

• The cppcheck issues look like a new check got introduced, this can be either ignored or fixed. Most look easy fixable.

Don't ignore, fix. Only cppcheck's own failings (false positives) can be ignored if there is no other formulation.

• clang needs now -latomic, then it should work.

That is very annoying. Why? The __atomic_compare_exchange should be translated into one instruction? What is happening here?

• The failing tests look more demanding, something is wrong there. Often, it's undefined behavior that got changed in a new compiler. There are tools to check this, let's see, -fsanitize=address -fsanitize=undefined helped me a lot to debug a wired memory alignment issue in an other project.

Yes, probably a compiler optimization change that exposes this. But it is a real problem that needs fixing. These fail running runtests. If you can reproduce it then you can fix it.

[hdiethelm]

So, new PR:
#4477

[grandixximo]

good news, #4478 came up from weblate, no warnings with my fix from weblate inside, so closing the PRs that fail and fix them in weblate, and waiting for a new PR is actually viable as a workflow, we can merge only fixed PR, which is great news, we can enforce html checks, eventually...

[hdiethelm]

Nice! That makes the workflow way simpler.
But #4477 needs to be merged first which makes new issues in translations visible. Like always, what should have been a simple one line PR results in a multi day effort due to newly discovered issues while checking... ;-)

[grandixximo]

I'm working trough the broken links, that will take a few iterations, there are about 1000 broken links to fix manually trough the crappy weblate UI...