make: Ensure documentation is cleaned up and regenerated when needed

- Files are not the only inputs to `texi', so we cannot rely on their
  modification times alone, to determine whether a rebuild is required.
  The new `redo-docs' always regenerates the texi file and thus all
  other formats.  Use that target before publishing the manual.

- Teach `html-dir' to only regenerate if a texi file has actually been
  touched.

- However when `html-dir' does regenerate, we must first remove all
  existing html files, to avoid files that used to be generated but
  are not being generated anymore, from sticking around.

3 files changed, 30 insertions, 19 deletions

diff --git a/Makefile b/Makefile
index 5db4f16..313fa36 100644
--- a/Makefile
+++ b/Makefile
@@ -23,6 +23,7 @@ help:
 	$(info make lisp             - compile elisp)
 	$(info make redo             - re-compile elisp)
 	$(info make docs             - generate all manual formats)
+	$(info make redo-docs        - re-generate all manual formats)
 	$(info make texi             - generate texi manuals)
 	$(info make info             - generate info manuals)
 	$(info make html             - generate html manual files)
@@ -69,15 +70,18 @@ help:
 
 ## Build #############################################################
 
-redo: clean-lisp lisp
-
 lisp:
 	@$(MAKE) -C lisp lisp
 	@$(MAKE) -C test lisp
 
+redo: clean-lisp lisp
+
 docs:
 	@$(MAKE) -C docs docs
 
+redo-docs:
+	@$(MAKE) -C docs redo-docs
+
 texi:
 	@$(MAKE) -C docs texi
 
diff --git a/default.mk b/default.mk
index 7c8aa95..ec3e277 100644
--- a/default.mk
+++ b/default.mk
@@ -43,14 +43,17 @@ GITSTATS_ARGS ?= -c style=https://magit.vc/assets/stats.css \
 ## Files #############################################################
 
 PKG       = magit
+PKGSTEXI  = magit magit-section
 PACKAGES  = magit magit-section git-commit
 
-TEXIPAGES = $(addsuffix .texi,$(filter-out git-commit,$(PACKAGES)))
-INFOPAGES = $(addsuffix .info,$(filter-out git-commit,$(PACKAGES)))
-HTMLFILES = $(addsuffix .html,$(filter-out git-commit,$(PACKAGES)))
-HTMLDIRS  = $(filter-out git-commit,$(PACKAGES))
-PDFFILES  = $(addsuffix .pdf,$(filter-out git-commit,$(PACKAGES)))
-EPUBFILES = $(addsuffix .epub,$(filter-out git-commit,$(PACKAGES)))
+ORGPAGES  = $(addsuffix .org,$(PKGSTEXI))
+TEXIPAGES = $(addsuffix .texi,$(PKGSTEXI))
+INFOPAGES = $(addsuffix .info,$(PKGSTEXI))
+HTMLFILES = $(addsuffix .html,$(PKGSTEXI))
+HTMLTOPS  = $(addsuffix /index.html,$(PKGSTEXI))
+HTMLDIRS  = $(PKGSTEXI)
+PDFFILES  = $(addsuffix .pdf,$(PKGSTEXI))
+EPUBFILES = $(addsuffix .epub,$(PKGSTEXI))
 
 ELS  = git-commit.el
 ELS += magit-section.el
@@ -225,8 +228,6 @@ DEPS += with-editor/lisp
 DOMAIN      ?= magit.vc
 CFRONT_DIST ?= E2LUHBKU1FBV02
 
-PUBLISH_TARGETS ?= html html-dir pdf
-
 DOCBOOK_XSL ?= /usr/share/xml/docbook/stylesheet/docbook-xsl/epub/docbook.xsl
 
 EPUBTRASH = epub.xml META-INF OEBPS
diff --git a/docs/Makefile b/docs/Makefile
index b9c5b5d..043c717 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -7,11 +7,12 @@ include ../default.mk
 
 docs: texi info html html-dir pdf
 
-texi: $(TEXIPAGES)
-info: $(INFOPAGES) dir
-html: $(HTMLFILES)
-pdf:  $(PDFFILES)
-epub: $(EPUBFILES)
+texi:     $(TEXIPAGES)
+info:     $(INFOPAGES) dir
+html:     $(HTMLFILES)
+html-dir: $(HTMLTOPS)
+pdf:      $(PDFFILES)
+epub:     $(EPUBFILES)
 
 ORG_ARGS  = --batch -Q $(ORG_LOAD_PATH) -l ol-man
 ORG_EVAL += --eval "(progn $$ORG_MAN_EXPORT)"
@@ -19,6 +20,10 @@ ORG_EVAL += --eval "(setq indent-tabs-mode nil)"
 ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)"
 ORG_EVAL += --funcall org-texinfo-export-to-texinfo
 
+redo-docs:
+	@touch $(ORGPAGES)
+	@make docs
+
 %.texi: %.org
 	@printf "Generating $@\n"
 	@$(EMACS) $(ORG_ARGS) $< $(ORG_EVAL)
@@ -46,7 +51,8 @@ HTML_FIXUP_MENU   = '/<\/body>/i<div id="s-css-s--menu"><\/div>'
 	@$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $<
 	@sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $@
 
-html-dir: $(TEXIFILES)
+%/index.html: %.texi
+	@$(RMDIR) $(HTMLDIRS)
 	@printf "Generating magit/*.html\n"
 	@$(MAKEINFO) --html -o $(PKG)/ $(MANUAL_HTML_ARGS) magit.texi
 	@for f in $$(find magit -name '*.html') ; do \
@@ -118,8 +124,8 @@ comma := ,
 empty :=
 space := $(empty) $(empty)
 
-publish: $(PUBLISH_TARGETS)
-	@printf "Uploading manuals... $(PUBLISH_TARGETS)\n"
+publish: redo-docs
+	@printf "Uploading snapshot manuals...\n"
 	@aws s3 cp $(PKG).html $(PUBLISH_TARGET)
 	@aws s3 cp $(PKG).pdf  $(PUBLISH_TARGET)
 	@printf "upload: ./$(PKG)/* to $(PUBLISH_TARGET)*\n"
@@ -132,7 +138,7 @@ publish: $(PUBLISH_TARGETS)
 	@aws cloudfront create-invalidation --distribution-id $(CFRONT_DIST) --paths \
 	"$(subst $(space),$(comma),$(addprefix $(PUBLISH_PATH),$(CFRONT_PATHS)))" > /dev/null
 
-release: $(PUBLISH_TARGETS)
+release: redo-docs
 	@printf "Uploading release manuals...\n"
 	@aws s3 cp $(PKG).html $(RELEASE_TARGET)
 	@aws s3 cp $(PKG).pdf  $(RELEASE_TARGET)