docs(html): KiCAD-inspired topbar, side TOC, language switcher, admonition tints

[grandixximo]

Re-implements the docs topbar on top of the merged docs/build/ layout (#4081). Supersedes the pre-#4081 prototype (766f2d9103).

What it adds

• Sticky topbar with the LinuxCNC logo on every page, matching asciidoctor's footer palette. Logo at docs/src/lcnc-docs.svg, copied into docs/build/html/ by the shared-asset rule.
• Side TOC via asciidoctor :toc=left; auto-hides below 800px.
• Language switcher (top-right), built from po4a.cfg plus a LANG_LABEL_<lang> map so po4a.cfg stays the single source of truth. Works on regular pages and manpages.
• Admonition tints (note/tip/warning/caution/important) with Unicode icons mapped onto asciidoctor's icons=font output, no FontAwesome dependency.

Per-page translation status

lang_switcher_postprocess.py walks the built tree, looks up each page's coverage in the per-language .po, and greys out switcher entries (and dead manpage-index links) below the POKEEP threshold (default 80%). POKEEP=30 on the make line surfaces in-progress translations; documented in contributing-to-linuxcnc.adoc, building-linuxcnc.adoc, and docs/README.adoc.

Notes

• Build-time injection only: docinfo-header.html from a .html.in template via docinfo=shared; gcode.html becomes gcode.html.in (po4a master) with per-language topbar fragments; the stale hardcoded Translations: list in index.tmpl is dropped in favour of the switcher.
• Verified with a full translated build (8 languages, 2387 translated pages).

[BsAtHome]

You are hiding translations and doing grayed out presentation? The data is still there and you deliberately restrict access to it. That is IMO a Bad Move^TM and user unfriendly.

If a translation is not worthy to show, then it should be removed entirely. Any cutoff level is always an arbitrary value and you have no idea which part you will hit. The large translation file may be only 10% done, but that can cover a complete section of the documentation, which you now are hiding.

The better way is to start splitting the translations into smaller units so that it becomes much easier to do a full translation for a part. At the moment, you just see a huge mountain of stuff to translate with no end in sight. Smaller units solve that. But it is for the future.

[grandixximo]

You are hiding translations and doing grayed out presentation? The data is still there and you deliberately restrict access to it. That is IMO a Bad MoveTM and user unfriendly.

Also this one, wasn't sure what to go for, mostly trying to avoid broken links, I'm not sure what you are proposing here, the only way is a % and it is arbitrary, but it's the standard as far as I looked around, the chapter split for translation does not belong here, is the bad move a blocker? What's the alternative for this PR?

[BsAtHome]

Per your comment:

lang_switcher_postprocess.py walks the built tree, looks up each page's coverage in the per-language .po, and greys out switcher entries

Why do this at all? If a language was translated and enabled in po4a.cfg, then it will be there. No buts, the config states it is available, then it is available.

You worry about (external) links? This is the devel tree doc, not a release, and there are no guarantees in development. How else can we reorganize? Reorgs break things.

(and dead manpage-index links)

Don't hide it. This stuff needs fixing, not hiding.

What's the alternative for this PR?

It is not about "alternative". The redesign is great. The details are being discussed.

[hansu]

It would be cool if we could get the whole TO in the left panel, like

And I would move the Navigation to the top, like the style of the Numpy docs

You are hiding translations and doing grayed out presentation? The data is still there and you deliberately restrict access to it. That is IMO a Bad MoveTM and user unfriendly.

But if a language has a translation status of 10% or I would even say <50%, I would tend to hide this language. I think a mix of languages is more irritating than a complete English doc. Then you cannot really use the browser translation function.

Would be nice if we could suppress this when only building for one language:

file:///home/cnc/linuxcnc-master-docs/docs/build/html/de/gcode.html
  Line: 57
  Code: 404 File `/home/cnc/linuxcnc-master-docs/docs/build/html/de/gcode.html' does not exist
 To do: The link is broken. Double-check that you have not made any typo,
        or mistake in copy-pasting. If the link points to a resource that
        no longer exists, you may want to remove or fix the link.

[BsAtHome]

You are hiding translations and doing grayed out presentation? The data is still there and you deliberately restrict access to it. That is IMO a Bad MoveTM and user unfriendly.

But if a language has a translation status of 10% or I would even say <50%, I would tend to hide this language. I think a mix of languages is more irritating than a complete English doc. Then you cannot really use the browser translation function.

You are undermining your argument by using "browser translation function". If you want the browser to translate, then you always should use the master (untranslated) documentation language (English) as the base for any automated translations... Not doing so would create Babel in extended fashion with aliens from Mars pitching in.

That actually touches the reason why or why not to do (full) documentation translations at all. The automated translations work very well for "casual" texts. However, highly technical documents range from usable to mediocre to poor to outright misleading when auto-translated. Secondly, this stuff is often running on systems that are isolated and no access to Internet or advanced tools. Local information is still relevant for these systems.

Hiding stuff is simply not the right way to solve the problem.

[hansu]

You are undermining your argument by using "browser translation function".

I mean if you have a text where one paragraph is English and the next one is in some other language and so on.
So if you are a person who have is very hard to read English you would enable browser translation. But I assume it gets problems when it expects English s source and there is text in other languages in between. So for that person this partly translated docs would not be very helpful.

But forget that idea. If we hide the partly translations, it is hard so see the status and what needs to be translated.
Maybe add a note/warning "This language is only XX% translated"

That actually touches the reason why or why not to do (full) documentation translations at all.

But how would you mark the chapters which are translated completely?

[BsAtHome]

That actually touches the reason why or why not to do (full) documentation translations at all.

But how would you mark the chapters which are translated completely?

That is a good question. Probably by separating or grouping (some of) the chapters in translation. But any change here needs to wait because it should be accompanied by rethinking and moving around much of the documentation (content) to make a more logical and coherent story.

[grandixximo]

@hansu doesn't the TOC already render on the left panel with this PR? Or am I missing something?

[hansu]

@hansu doesn't the TOC already render on the left panel with this PR? Or am I missing something?

With whole I mean the whole documentation or at least the chapter and not only the toc of the regarding adoc document.
So currently it's only like this and that brings not much benefit.

[grandixximo]

@hansu in the other picture you changed the LinuxCNC Home Page link for Documentation, but the top left logo already links back to Documentation main page, I think it should stay linking back to linuxcnc.org not documentation, or you were thinking something different?

[hansu]

I thought we could have the same header for the wlo page and the docs. So the top left logo then should point to www.linuxcnc.org

[grandixximo]

The logo is specifically for the docs, with the penguin reading the docs book, its expected to bring you back to the main doc page, where it is still present up top, that's the most sensible IMO, clicking the doc logo and end up in linuxcnc.org and having to navigate back defeats the purpose of the logo, and moves it in the Documentation link, I don't find reason to do this switcharoo, feels confusing, I don't find it intuitive for the user, is that how other doc website behave? Kicad on which I took some ideas, and NumPhy which you linked, seem to both behave as I would expect.

[hansu]

Yeah the logo then should be the general one, not the docs logo.
But maybe it's too much for to have also the wlo page in the same look.
So then have the header for the docs like this:

For the complete TOC I think we need to include all adoc files in one adoc file like it is done in Master_Documentation.adoc.
No idea if that would change something for the po4a config.

[grandixximo]

So then have the header for the docs like this:

agreed

For the complete TOC I think we need to include all adoc files in one adoc file like it is done in Master_Documentation.adoc. No idea if that would change something for the po4a config.

The TOC can be extracted at build time, working on it, since the TOC is huge, keep everything expanded? or only expand section where you landed? I will need to set focus on the landed item in the TOC if we want to avoid one line of JS.

[hansu]

The TOC can be extracted at build time, working on it, since the TOC is huge, keep everything expanded? or only expand section where you landed?

Keep everything collapsed when opening, like on the docs main page. And then expand the current section or subsection.

[grandixximo]

@hansu Pushed the "complete" sidebar TOC. Only the book you land on is expanded; the others stay collapsed. The page's own local TOC is injected under its entry, so big per-page trees (like gcode) are not lost. It also scrolls to the active entry on load. I tried it and it works well.

With this, almost everything lives in the left bar now. The only thing still outside it is the manpage listing. I think it could be worth moving the manpages into the left panel too, and that gives us space to completely redesign the landing page, like proposed elsewhere with the main topics users visit the docs for. Probably a separate PR though, and #4109 should merge first.

[grandixximo]

The TOC can be extracted at build time, working on it, since the TOC is huge, keep everything expanded? or only expand section where you landed?

Keep everything collapsed when opening, like on the docs main page. And then expand the current section or subsection.

I tried with everything collapsed other than current section, but it was wasting a lot of space on short chapters, so i went with full expansion, I think it looks better, but I can switch back, it does not make much difference, I think it may save some clicks, but adds a few more scrolls, try it like this, see what you think. I think scrolls are less expensive as the mouse can be anywhere withing the left bar, while click on the arrow require some finesse...

Edit:
I noticed some fields are missing from the sidebar TOC, this is because they are also missing from the PDF, but I think the correct way is to add them in the PDF as well, like

• getting-started/hardware-interface
• gui/gladevcp-panels
• drivers/mesa_modbus
• code/writing-tests

We should have a single source of truth for the TOC, to avoid these issues, correct?

[BsAtHome]

We should have a single source of truth for the TOC, to avoid these issues, correct?

We should not try to fix all content and organizational problems with this PR. These issues and details are too numerous IMO.

If we strive to make a functional site that is not less than the current version, then we can start talking about detailed issues later.

[grandixximo]

Ok, it will be missing, with fallback to have the local TOC on top of main TOC in this PR, then separate PR to fix the missing entry in the main TOC and PDF entries.

Another issue I ran into, while moving the links to the top bar, they'll stay in English till translation passes from weblate, I cannot reuse what was done for the landing page :-(

[hansu]

The header looks nice, but the TOC hasn't changed for me.

Edit: I didn't notice you force-pushed this feature away

[hansu]

We should not try to fix all content and organizational problems with this PR. These issues and details are too numerous IMO.

But isn't this PR dedicated to the sidebar? So why not do it right the first time?

[grandixximo]

The whole-document tree is injected at the end of the build by lang_switcher_postprocess.py, and it nests each page's own section list under the active entry, so it needs the freshly generated HTML. Building on top of an already-processed tree won't refresh it. A clean build fixes it:

cd src
make clean && make -j$(nproc) htmldocs

Deleting just the stamps isn't enough. The page HTML has to be regenerated so the per-page TOCs exist for nesting. Here's how it looks here:

[grandixximo]

[BsAtHome]

We should not try to fix all content and organizational problems with this PR. These issues and details are too numerous IMO.

But isn't this PR dedicated to the sidebar? So why not do it right the first time?

Indeed it is. But trying to fix contextual details may not survive and need to be reorganized anyway. The main issue is to port the main body into a new jacket without surgically replacing the body to fit the jacket ;-)

[hansu]

Weird, I don't get this part, even with git clean: