docs(html): KiCAD-inspired topbar, side TOC, language switcher, admonition tints#4113
docs(html): KiCAD-inspired topbar, side TOC, language switcher, admonition tints#4113grandixximo wants to merge 12 commits into
Conversation
grandixximo
force-pushed
the
docs/topbar-greyout-on-build
branch
from
42cfdf5 to
133a6d9
Compare
|
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. 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. |
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? |
|
Per your comment:
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.
Don't hide it. This stuff needs fixing, not hiding.
It is not about "alternative". The redesign is great. The details are being discussed. |
|
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 
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: |
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. |
I mean if you have a text where one paragraph is English and the next one is in some other language and so on. But forget that idea. If we hide the partly translations, it is hard so see the status and what needs to be translated.
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. |
|
@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. |
|
@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? |
|
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 |
|
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. |
|
Yeah the logo then should be the general one, not the docs logo. For the complete TOC I think we need to include all adoc files in one adoc file like it is done in |
agreed
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. |
Keep everything collapsed when opening, like on the docs main page. And then expand the current section or subsection. |
|
@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. |
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:
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. |
|
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 :-( |
grandixximo
force-pushed
the
docs/topbar-greyout-on-build
branch
from
5b77473 to
0a8c09e
Compare
|
The header looks nice, but the TOC hasn't changed for me. Edit: I didn't notice you force-pushed this feature away |
But isn't this PR dedicated to the sidebar? So why not do it right the first time? |
|
The whole-document tree is injected at the end of the build by 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: |
|
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 ;-) |
|
Weird, I don't get this part, even with git clean: 
|
|
The build is no longer stable. (your tree) ./autogen.sh
./configure --enable-build-documentation=html --enable-build-documentation-translation
make -O -j8 # Build full
make -O -j8 # Builds partialSecond output starts with: |
|
Once you land on any secondary page, for example clicking the first link There is a top-level index link (for the current language) missing in the navigation bar. Even if we are going to change content later, you need to be able to navigate back in a logical way because the established hierarchy needs to be consistent. |
|
The logo, is a link back to the main, doesn't work? |
Yes, but that links to |
|
I can make that, language sensitive, will that work? Or add navigation buttons within the top bar? Like back and home? So home is language home, and logo is back to main index? And back is just one level up in the hierarchy? Do we have pages for the entire hierarchy? |
Yes, that should be enough.
No complexity required.
Temporary home is
The |
|
In the navigation bar: |
…ition tints Re-implemented on top of PR LinuxCNC#4081's docs/build/ layout. Replaces the previous prototype branch (commit 766f2d9) which targeted the pre-LinuxCNC#4081 docs/html/ paths. - Sticky topbar with LinuxCNC logo on every page; matches asciidoctor's footer colour scheme. Logo SVG lives at docs/src/lcnc-docs.svg and is copied into docs/build/html/ by the shared-asset rule. - Side TOC via asciidoctor :toc=left; auto-hides below 800px (CSS). - Language switcher in the topbar (top-right) built from po4a.cfg + a LANG_LABEL_<lang> map in Submakefile, so po4a.cfg stays the single source of truth. - Admonition blocks (note/tip/warning/caution/important) tinted by type with Unicode icons mapped onto asciidoctor's icons=font output (no FontAwesome dep). Build-time injection: - docs/src/docinfo-header.html generated from .html.in template; asciidoctor pages pick it up via docinfo=shared. - docs/src/gcode.html renamed to gcode.html.in (po4a master); per-lang docs/build/html/<lang>/gcode.html generated from po4a's gcode-raw.html + per-lang topbar fragment. - Per-lang docs/build/html/<lang>/index.html similarly gets topbar injection + CSS path rewrite + objects/index.incl appended so the manpage list is present on translated indexes too. - docs/src/index.tmpl's hardcoded Translations: list dropped; topbar switcher replaces it. - English + translated manpage HTML rules pass lcnc-lang-label and lcnc-subpath so the switcher works on manpages. Per-page language indication via lang_switcher_postprocess.py: walks docs/build/html at end of build, looks up each page's master in each lang's .po, counts msgid-with-master-loc vs translated, toggles class=lcnc-lang-unavail on the <li> when coverage falls below POKEEP (default 80). Same pass marks details-list entries (manpage index lists) whose target file does not exist for the current language. Idempotent: same toggle pattern across re-runs. POKEEP is overridable on the make command line (POKEEP=30 surfaces in-progress translations); contributing-to-linuxcnc.adoc, building-linuxcnc.adoc, and docs/README.adoc document the knob. CSS adds .lcnc-lang-unavail and .lcnc-link-unavail rules: dim text, pointer-events: none, cursor not-allowed; .lcnc-link-unavail also adds strikethrough for the index list context.
Move the native language display names out of the makefile into docs/src/lang-labels (tag<ws>name). A language in po4a.cfg without an entry falls back to its tag with a make warning.
Drop the POKEEP percent-threshold hiding: every present translation stays clickable; the switcher only greys a target that does not exist. A page below 100% now carries a no-JS banner below the topbar stating its completeness, tinted red(0%) to green(100%).
Build a nested nav tree from the Master_*.adoc structure and inject it at the top of asciidoctor's left TOC (no JS, native <details>). Each page gets the tree with its branch expanded, its entry active, and its own section list nested under it. Section-less pages get a scaffolded sidebar. CSS-drawn markers override asciidoctor's absolute summary marker so they stay in flow.
Add the LinuxCNC site links (Home, Wiki, Forum, Source, G-Code reference) centred in the topbar so they are reachable from every page, and drop the duplicate block from the landing page.
The lang-switcher post-processor rewrites every generated HTML page in place as the final step, which bumped their mtimes past three stamps that had consumed the same files earlier in the build. A second make then re-fired the image copy, the shared-asset copy and the complist stamp (and the .htmldoc-stamp / checkref that depend on it), so the build never settled. - .html-images-stamp now depends on .lang-switcher-stamp, so it reads the final post-processed HTML and stays newer than it. - .copy-asciidoc-stamp's gcode.html dependency and .gen_complist-stamp's MAN_HTML_TARGETS dependency become order-only: both only need the files built, not their (later-rewritten) content. A second and third make are now true no-ops.
The logo linked to the generic index.html, which always redirects to English; on a translated page that silently dropped the language. The post-processor now retargets it to <lang>/index.html.
Expand only the branch leading to the current page instead of the whole book, and put the page's own section list in a collapsed "On this page" details, so sibling pages in the section stay visible.
grandixximo
force-pushed
the
docs/topbar-greyout-on-build
branch
from
0a8c09e to
8b41e18
Compare
|
I will remove the "on this page" menu The logo is language gnostic now, and the build should be clean, I'll test the build a couple of times before pushing |
The active page is now the disclosure itself: its name is the summary that folds its section list, instead of a separate "On this page" block. Match summary size to the sibling links.
|
@hansu still don't see it? |
|
The admonition icons are not showing. It seems that the |
|
Build is now stable and the sidebar index working as expected with the added fold. Now you can find stuff :-) One thing I noted is the instability of the scrollbar in both sidebar and main page. I have to apply the scroll-wheel to make it visible and catch it while still there. Then, when done, it vanishes again. |
No :'( 
|
what browser? does serving it with a server fixes it? |
I like the BootStrap style, I'm going for that |
I think I know why, will push a fix soon... |
Replace the unicode-glyph admonition icons (font-dependent, often not rendered) with Bootstrap Icons drawn as a CSS mask, painted with each block's own colour so they tint per type in both themes. The word label is kept off-screen as the accessible text. Adds the five SVGs to the shared HTML assets and an Expat copyright stanza.
The whole-document sidebar and topbar were only injected when BUILD_DOCS_TRANSLATED=yes, so an English-only build produced pages with no navigation at all. The sidebar is derived from the Master_*.adoc structure and is language-independent, so gate the post-processor on BUILD_DOCS_HTML instead; with no languages the switcher and banner just go idle. The post-processor now also accepts an empty language list.
Transparent black-line PNG diagrams vanished on the dark page; only SVGs got a white backing. Back every figure with white (opaque screenshots cover it, so no frame); keep the padded white card for SVGs.
3 participants
Re-implements the docs topbar on top of the merged
docs/build/layout (#4081). Supersedes the pre-#4081 prototype (766f2d9103).What it adds
docs/src/lcnc-docs.svg, copied intodocs/build/html/by the shared-asset rule.:toc=left; auto-hides below 800px.po4a.cfgplus aLANG_LABEL_<lang>map sopo4a.cfgstays the single source of truth. Works on regular pages and manpages.icons=fontoutput, no FontAwesome dependency.Per-page translation status
lang_switcher_postprocess.pywalks 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 thePOKEEPthreshold (default 80%).POKEEP=30on the make line surfaces in-progress translations; documented incontributing-to-linuxcnc.adoc,building-linuxcnc.adoc, anddocs/README.adoc.Notes
docinfo-header.htmlfrom a.html.intemplate viadocinfo=shared;gcode.htmlbecomesgcode.html.in(po4a master) with per-language topbar fragments; the stale hardcodedTranslations:list inindex.tmplis dropped in favour of the switcher.