Skip to content

Rework the documentation site: new content structure and fully automated sync/translation pipeline - #199

Draft
Salvialf wants to merge 164 commits into
masterfrom
rework
Draft

Rework the documentation site: new content structure and fully automated sync/translation pipeline#199
Salvialf wants to merge 164 commits into
masterfrom
rework

Conversation

@Salvialf

@Salvialf Salvialf commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

This replaces the old, broken Jenkins-based documentation pipeline (issue #166) with a fully automated one, alongside a complete restructuring of the site's content layout. It's a large diff; this description is being published early, before every dependency has landed, specifically so reviewers can start orienting themselves and reviewing incrementally rather than facing the whole thing cold. It will be kept up to date as the remaining pieces (see "Do not merge until" below) land.

A note on reviewing this: GitHub's web UI can't render this PR's diff (47,978 changed files, ~700k insertions / ~1.2M deletions): the "Files changed" tab will show empty. Review it locally instead, via git diff master rework, or commit by commit through the Commits tab, which does render individually. You can also just browse the final state directly on the rework branch on GitHub, without needing a diff at all.

What changed

Content structure

  • Every content area (general sections, core, plugins, plugins_contributor) moved from a language-prefixed scheme (/<lang>/<category>/...) to a category/version/plugin-first one (/<category>/<lang>/..., /core/<version>/<lang>/..., /plugins/<category>/<pluginid>/<lang>/...).
  • Years of accumulated duplication removed: the repo's working tree shrank from ~3.5GB to ~399MB.
  • The protocol-compatibility cluster (blea/camera/edisio/enocean/rfxcom/zigbee/zwave), the last remaining block of duplicated content, was removed outright in favor of pointing to compatibility.jeedom.com, which already serves as the canonical source for this content.
  • css/js/img/fonts consolidated under assets/.
  • Plugin category-index pages (plugins/<category>/<lang>/index.md) are now generated from data (_data/plugins[_contributor]/<category>.yml) instead of hand-maintained Markdown tables, closing the door on the historical duplication bugs that came from editing those by hand.

Navigation and link resolution

init.js was split into config.js/urlResolver.js/tools.js/404.js/index.js, and link resolution was substantially upgraded, not just adapted to the new URL scheme:

  • Any link now respects the visitor's actual language preference, not just the one baked into the link, on every valid page (not only 404s).
  • Retired Core versions fall back to the current version automatically, in any context (old-scheme URL, direct hit, with or without a language segment).
  • Incomplete-but-recognizable URLs resolve instead of 404ing (e.g. a real page missing only its language segment). This is a general fallback: localizeHref runs on the raw path and redirects only if the result differs, not a fixed list of known-broken shapes, so it should keep absorbing future URL-shape regressions without new dedicated rules.

Every redirect only fires if the computed target genuinely differs from the current path (loop-safe, verified against ~30 scenarios including adversarial slugs like migration-to-4.6-guide). All of this happens client-side after a real 404 has already been served, so search engines still see genuine 404s; only human visitors benefit.

Automation

  • jeedom/workflows/docs-publish.yml: shared cross-repo publish workflow (core + plugin destinations, category/alias resolution).
  • jeedom/core#3460 / delestage's docs.yml: translate (via jeedom/jeetranslate-docs) + publish, per-repo. Also validated on calendar via its own stable release in the meantime. publish jobs are intentionally left commented out in all of these until this PR merges (publishing before that would write into the still-duplicated current layout).
  • phpdoc.yml: pull-based PHPDoc regeneration, lives entirely in documentations, validated end-to-end on its own disposable branch before merging.
  • docs-translations.yml: general-content translation via DeepL (jeetranslate-docs), validated category by category on a disposable branch (all 12 categories: compatibility, concept, contribute, dev, home, howto, howtoadvance, installation, legal_notice, mobile, premiers-pas, presentation). Several real mistranslation bugs were found and fixed along the way, both in jeetranslate-docs's own parser and via glossary entries. Runs as a single job covering all 12 categories with a shared translation memory. Its push trigger targets master, not rework, so it stays dormant from this merge alone.

⚠️ While this is pending

Please hold off on publishing new official-plugin stable releases until this merges. docs-publish's destination logic and the category-index generation are both changing here; a stable release landing on the old scheme in the meantime would need its diff manually reconciled afterward instead of just flowing through the new pipeline.

⚠️ Do not merge until

  • market's documentationSync (icon sync, category-index generation/reconciliation, obsolete-plugin cleanup, replacing jenkins::pluginBeta/pluginStable/pluginStableContributor) is reviewed and merged. The code is written, not yet opened as a PR.
  • The Jenkins jobs Market/beta, Market/stable, Market/stable_contributor are confirmed stopped. They should simply stop being triggered once market's PR above deploys (it removes the calls that trigger them), nothing to actively decommission on the Jenkins side itself, but confirm before considering this done. Do not touch compatibility_zwave, compatibility_z2m, translate_compatibility, or core_release: unrelated jobs feeding compatibility.jeedom.com and core's own release tagging.

Immediately after merging

  • Uncomment the publish job in jeedom/core's docs.yml (#3460), delestage's docs.yml, and calendar's docs.yml, all gated on this exact merge.
  • Delete the disabled translate::updateTranslation cron and its now-dead market stub method for good (confirmed safe, just not yet done).

Salvialf added 30 commits August 3, 2026 23:30
Salvialf and others added 16 commits August 14, 2026 20:47
…ns and paren-splitting artifacts in en_US/es_ES/de_DE
Integrate the validated DeepL documentation translation pipeline into rework
@Salvialf Salvialf self-assigned this Aug 14, 2026
@Salvialf Salvialf added documentation Improvements or additions to documentation enhancement New feature or request labels Aug 14, 2026
@Salvialf Salvialf linked an issue Aug 14, 2026 that may be closed by this pull request
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Rework translation system

1 participant