Ci doc build backport 2.9

[hdiethelm]

Backport of #4150 to 2.9

Feel free to merge if useful or drop if not needed, took me just a few minutes.

I left the commits as they where, I hope there is not to much trouble merging 2.9 to master.

Edit: I also added @grandixximo's commit that cancels outdated CI run's for PR's

[hdiethelm]

Hmm. github is again sleepy today. Let's see how it looks tomorrow.

[grandixximo]

Took almost 4 hours but it passed, @hdiethelm ready to merge?

I cancelled the stuck CI build manually.

[hdiethelm]

Took almost 4 hours but it passed, @hdiethelm ready to merge?

I cancelled the stuck CI build manually.

Yes,i just wanted to check if the contents of the tar look correct.

BTW:
It looks like the german translations are broken, but probably not caused by this PR, the contents of the tar look good, same issue if I open the html/de/index.html when built locally. It might work on the server but it also might not.

It might be good to investigate before uploading this artifact to the homepage server.

[grandixximo]

You were lucky, because today sid is broken altogether...
I will try to have a clean worktree with 2.9 see why german is broken

[hdiethelm]

I added the sid allow fail in this PR, so all fine anyway... ;-) Thanks!

[grandixximo]

I looked into the broken German index. It is not caused by this PR, but here is a fix if useful.

html/de/index.html references index.css, linuxcnc-logo-chips.png, plus.png and minus.png with bare relative paths, but those assets only exist in the html/ root next to the English index. They are never copied into html/de/, so the German index loads with no stylesheet, a broken logo and broken expand/collapse icons. The chapter pages are fine because asciidoc sets stylesdir for them; only the hand-written index escapes that.

The per-language index rule just needs to copy those four assets into each html/<lang>/ dir:

diff --git a/docs/src/Submakefile b/docs/src/Submakefile
@@ -518,6 +518,8 @@ $(DOC_DIR)/html/%/index.html: $(DOC_SRCDIR)/index_%.tmpl ../VERSION $(DOC_SRCDIR
 	cat $(filter-out ../VERSION, $^) | \
 		sed "s/@VERSION@/`cat ../VERSION`/" | \
 		if [ "yes" != "$(BUILD_DOCS_TRANSLATED)" ]; then sed '/@TRANSLATIONS@/,/@ENDTRANSLATIONS@/d' ; else grep -Ev '@(END)?TRANSLATIONS@'; fi > $@
+	cp -f $(DOC_DIR)/html/index.css $(DOC_DIR)/html/linuxcnc-logo-chips.png \
+		$(DOC_DIR)/html/plus.png $(DOC_DIR)/html/minus.png $(dir $@)
 
 $(DOC_DIR)/html/index.html: $(DOC_SRCDIR)/index.tmpl objects/index.incl $(DOC_SRCDIR)/index.foot ../VERSION $(DOC_SRCDIR)/Submakefile

Tested with a full build-doc.sh: the German index now renders styled, and verify-clean-repo stays clean.

[hdiethelm]

Thanks! Just going to the homepage https://linuxcnc.org/docs/html/de/ shows the same issue, some stuff is missing. I assume the browser just does some auto fixing, so it still somewhat works:

You can even do this locally, F12, move to network and shift-reload, so you see if files are missing.

Also a lot of stuff is duplicated in 2.9, just spot checked one file:

find -name upgrading-to-2.9.png
./de/getting-started/images/upgrading-to-2.9.png
./nb/getting-started/images/upgrading-to-2.9.png
./zh_CN/getting-started/images/upgrading-to-2.9.png
./es/getting-started/images/upgrading-to-2.9.png
./fr/getting-started/images/upgrading-to-2.9.png
./hu/getting-started/images/upgrading-to-2.9.png
./getting-started/images/upgrading-to-2.9.png

So I don't have a to bad conscience duplicating a bit more.

@BsAtHome: I hope you are ok with this. I know this is not a real fix, more a workaround, but I won't fix all doc build for 2.9.

[hdiethelm]

Just found, even nicer than manually checking:
https://validator.w3.org/checklink?uri=https%3A%2F%2Flinuxcnc.org%2Fdocs%2Fhtml%2Fde%2F&hide_type=all&depth=&check=Check#results1

And for local usage, first one I found, there are others:
https://github.com/wjdp/htmltest

There is a docker image, it should be easy to integrate in CI.

Only disadvantage: A short test shows a ton of missing links. Looks like more is broken than working. Just go to https://linuxcnc.org/docs/html/de/hal/components.html and click on a link.

[grandixximo]

2.10 docs fix most of this stuff, but in 2.10 docs are built with asciidoctor now, but maybe some submake file stuff can be ported back, having working links on 2.9 docs is not a bad idea, but it might take some trial and error, are you expanding the scope here? or calling it a day? they are not any worse than they were, but you are welcome to fix them, here or in another PR, this one stays as CI doc build, and removing picture executable perm.