docs: deduplicate built HTML images into a shared image/ tree

The HTML doc build copies every referenced image into each language and
topic directory, so the built tree carries the same bytes many times over
(238 MB of images, only 30 MB unique).

Add docs/src/tools/dedup-images.py: it collapses byte-identical images
(SHA-256) into a shared root image/ tree, keeps only translated overrides
under <lang>/image/, and rewrites every src and click-to-enlarge href to
match. Dry-run by default, idempotent, and self-verifying: after --apply it
re-resolves every reference and fails if any is broken.

Wire it into the htmldocs build as a final .dedup-images-stamp step. The
tool preserves the mtime of every HTML file it rewrites, so a second
`make htmldocs` does no work.

On the full translated tree this takes the build output from 325 MB to
119 MB (images 238 MB to 30 MB) with all references verified.

Author: grandixximo

docs/src/Submakefile

@@ -573,7 +573,7 @@ $(DOC_OUT_HTML)/pdf/index.html: $(PDF_TARGETS) ../scripts/make-docs-pdf-index
 	@mkdir -p $(dir $@)
 	$(Q)../scripts/make-docs-pdf-index
 
-htmldocs: svgs_made_from_dots .htmldoc-stamp checkref_en
+htmldocs: svgs_made_from_dots .htmldoc-stamp .dedup-images-stamp checkref_en
 
 # When translations are enabled, the .adoc files in $(L)/ are produced by
 # the translateddocs target (po4a).  Teach make how to ask for them: the
@@ -595,6 +595,13 @@ endif
 .htmldoc-stamp: .copy-asciidoc-stamp $(DOC_DIR)/.gen_complist-stamp $(HTML_TARGETS) .images-stamp .include-stamp $(DOC_OUT_HTML)/asciidoctor.css $(DOC_OUT_HTML)/rouge-github.css .lang-switcher-stamp
 	touch $@
 
+# Collapse byte-identical images into a shared image/ tree and rewrite refs.
+# Runs last; the tool preserves HTML mtimes so a second `make htmldocs` is a
+# no-op.
+.dedup-images-stamp: $(DOC_SRCDIR)/tools/dedup-images.py .htmldoc-stamp
+	$(Q)python3 $(DOC_SRCDIR)/tools/dedup-images.py --html-root $(DOC_OUT_HTML) --apply
+	@touch $@
+
 # Inject the whole-document sidebar/topbar and grey out missing language-
 # switcher entries.  Runs last (depends on every HTML target) and is
 # idempotent.  Gated on BUILD_DOCS_HTML, not translations: the sidebar comes
@@ -705,7 +712,7 @@ checkref_en: $(DOC_DIR)/.checkref-english-stamp
 # (w3c-linkchecker disables file:// URIs), so the tree may carry accumulated
 # broken links.  Report them without breaking the build for now; drop this
 # flag once the backlog is cleared so regressions fail the build again.
-$(DOC_DIR)/.checkref-english-stamp: $(DOC_TARGETS_HTML_EN) $(DOC_OUT_HTML)/en/index.html $(DOC_OUT_HTML)/en/gcode.html .htmldoc-stamp
+$(DOC_DIR)/.checkref-english-stamp: $(DOC_TARGETS_HTML_EN) $(DOC_OUT_HTML)/en/index.html $(DOC_OUT_HTML)/en/gcode.html .htmldoc-stamp .dedup-images-stamp
 	$(DOC_SRCDIR)/checkref --warn-on-failure English $(filter %.html,$^)
 	@touch $@
 
@@ -1313,6 +1320,7 @@ docclean:
 	-rm -f $(DOC_SRCDIR)/*/*.html
 	-rm -rf $(DOC_FONT_DIR)
 	-rm -f .htmldoc-stamp
+	-rm -f .dedup-images-stamp
 	-rm -f .copy-asciidoc-stamp
 	-rm -f .adoc-images-stamp
 	-rm -f .html-images-stamp