refactor(makefile): sphinx-build make mode

Refactor this to reduce some redundant logic, simplify and describe
variable blocks, and use the sphinx-build make mode.

Newer versions of sphinx-quickstart have started rolling out make mode.
This provides a useful help note and allows users to try multiple
builders very easily. I believe we should redirect most targets through
this new mode.

Unfortunately this mode appends the builder name to the output path.
Given that our current software-dl.ti.com deployment scheme relies on a
specific output path, I've added a "ti" target to provide the older
behavior and made it the default.

The normal "html" builder will use the standard sphinx-build output
scheme with only one directory corresponding to the platform and os
values. The version will be assumed to be unnecessary in this mode.

Signed-off-by: Randolph Sapp <[email protected]>

Author: StaticRocket

Makefile

@@ -1,76 +1,70 @@
-# Makefile for Sphinx documentation
-#
-
-default: html
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-OS           ?= linux
-
-_UC = $(shell echo '$1' | tr '[:lower:]' '[:upper:]')
-_LC = $(shell echo '$1' | tr '[:upper:]' '[:lower:]')
-
-DEVFAMILY_UP=$(call _UC,${DEVFAMILY})
-OS_LOW=$(call _LC,${OS})
-
-mkfile_path = $(abspath $(lastword $(MAKEFILE_LIST)))
-export ROOTDIR = $(dir $(mkfile_path))
-$(info ROOTDIR is $(ROOTDIR))
-
-$(info DEVFAMILY is $(DEVFAMILY_UP))
-
-ifeq ($(OS_LOW), android)
-  # For Android, AM67A and AM67 have their own device directories
-  ifeq ($(DEVFAMILY_UP), $(filter $(DEVFAMILY_UP), J721E J7200 J721S2 J784S4 AM68 AM69 J722S J742S2 AM68A AM69A TDA4VM))
-    CONFDIR = source/devices/J7_Family/${OS_LOW}
-  else
-    CONFDIR = source/devices/$(DEVFAMILY_UP)/${OS_LOW}
-  endif
-else
-  # For Linux and other OSes, use J7_Family grouping including AM67A and AM67
-  ifeq ($(DEVFAMILY_UP), $(filter $(DEVFAMILY_UP), J721E J7200 J721S2 J784S4 AM68 AM69 J722S AM67 J742S2 AM68A AM67A AM69A TDA4VM))
-    CONFDIR = source/devices/J7_Family/${OS_LOW}
-  else
-    CONFDIR = source/devices/$(DEVFAMILY_UP)/${OS_LOW}
+# User defined variables for Sphinx
+SPHINXOPTS     ?=
+SPHINXBUILD    ?= sphinx-build
+SOURCEDIR       = source
+
+# User defined variables for custom plugins
+DEVFAMILY      ?= AM62X
+OS             ?= linux
+
+# Case modification functions, to assist with custom plugins
+_UC = $(shell printf '%s' '$(1)' | tr '[:lower:]' '[:upper:]')
+_LC = $(shell printf '%s' '$(1)' | tr '[:upper:]' '[:lower:]')
+
+# Export variable overrides for custom plugins
+override DEVFAMILY      := $(call _UC,$(DEVFAMILY))
+override OS             := $(call _LC,$(OS))
+override ROOTDIR        := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+export DEVFAMILY OS ROOTDIR
+
+# Configuration directory, complicated because of Jacinto
+CONFDIR = $(SOURCEDIR)/devices/$(DEVFAMILY)/$(OS)
+ifneq ($(filter $(DEVFAMILY), J721E J7200 J721S2 J784S4 AM68 AM69 J722S AM67 J742S2 AM68A AM67A AM69A TDA4VM),)
+  # For Linux and other OSes, use J7_Family
+  CONFDIR = $(SOURCEDIR)/devices/J7_Family/$(OS)
+  ifeq ($(OS), android)
+    # For Android, AM67A has their own device directories
+    ifneq ($(filter $(DEVFAMILY), AM67 AM67A),)
+      CONFDIR = $(SOURCEDIR)/devices/$(DEVFAMILY)/$(OS)
+    endif
   endif
+  # Print the new variable since this logic is likely to break
+  $(info CONFDIR = "$(CONFDIR)")
 endif
 
-$(info CONFDIR is $(CONFDIR))
+# These can be overridden if necessary
+VERSION         = $(file <$(CONFDIR)/version.txt)
 
-VERSION   = $(shell cat ${CONFDIR}/version.txt)
-SOURCEDIR = source
-BUILDDIR  = build/processor-sdk-${OS_LOW}-${DEVFAMILY_UP}/esd/docs/${VERSION}
+# TI specifc deployment variables
+BUILDDIR        = build/processor-sdk-$(OS)-$(DEVFAMILY)
+ti : BUILDDIR   = build/processor-sdk-$(OS)-$(DEVFAMILY)/esd/docs/$(VERSION)
 
-# User-friendly check for sphinx-build
-ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from https://sphinx-doc.org/)
-endif
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
+# Internal additions to SPHINXOPTS
 CONFLOC         = -c $(ROOTDIR)
-VEROPTS         = -D version=${VERSION} -D release=${VERSION}
+VEROPTS         = -D version=$(VERSION) -D release=$(VERSION)
 GIT_HASH        = -D html_context.commit="$(shell git rev-parse --short HEAD)"
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(CONFLOC) $(VEROPTS) $(GIT_HASH)
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+DOCTREE         = -d $(BUILDDIR)/doctrees
+SPHINXOPTS     := $(strip $(CONFLOC) $(VEROPTS) $(GIT_HASH) $(DOCTREE) $(SPHINXOPTS))
 
-.PHONY: help clean config html
+# Give some information on the command line about the build
+$(info DEVFAMILY = "$(DEVFAMILY)")
+$(info OS = "$(OS)")
+$(info ROOTDIR = "$(ROOTDIR)")
+$(info VERSION = "$(VERSION)")
+$(info BUILDDIR = "$(BUILDDIR)")
 
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
+.PHONY: default lint
 
-clean:
-	rm -rf "$(BUILDDIR)"
+default: ti
 
 lint:
 	rstcheck -r "$(SOURCEDIR)"
 
-html: 
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)"
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)."
+# Backwards compatible build target that preserves the old output path, for now
+ti:
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+# Pass everything else back to Sphinx, as they have their own "help" function to
+# list available builders, and their own "clean" function
+%::
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)