Build the wolfTPM manual from the wolfSSL/wolfTPM source repository

.github/workflows/build-check.yml

@@ -60,10 +60,13 @@ jobs:
       run: cd wolfSSH && export PATH=$PATH:"/home/runner/work/documentation" && make html
     - name: wolfssh pdf
       run: cd wolfSSH && export PATH=$PATH:"/home/runner/work/documentation" && make pdf
-    - name: wolftpm html
-      run: cd wolfTPM && export PATH=$PATH:"/home/runner/work/documentation" && make html
-    - name: wolfTPM pdf
-      run: cd wolfTPM && export PATH=$PATH:"/home/runner/work/documentation" && make pdf
+    - name: Pin wolfTPM source for this build
+      run: |
+        ref=$(git ls-remote https://github.com/wolfSSL/wolfTPM.git refs/heads/master | cut -f1)
+        test -n "$ref"
+        echo "WOLFTPM_REF=$ref" >> "$GITHUB_ENV"
+    - name: wolftpm html and pdf
+      run: cd wolfTPM && export PATH=$PATH:"/home/runner/work/documentation" && make
     - name: wolfmqtt html
       run: cd wolfMQTT && export PATH=$PATH:"/home/runner/work/documentation" && make html
     - name: wolfmqtt pdf

Dockerfile

@@ -28,8 +28,9 @@ ARG MANPATH
 ARG PDFFILE
 ARG V
 ARG WOLFCOSE_REF=main
+ARG WOLFTPM_REF=master
 WORKDIR /src/wolfssl/${MANPATH}
-RUN make pdf V=${V} WOLFCOSE_REF=${WOLFCOSE_REF}
+RUN make pdf V=${V} WOLFCOSE_REF=${WOLFCOSE_REF} WOLFTPM_REF=${WOLFTPM_REF}
 
 # Build wolfSSL HTML
 FROM wolfssl-stage1 AS wolfssl-stage2
@@ -39,6 +40,8 @@ ARG V
 WORKDIR /src/wolfssl/${MANPATH}
 RUN if [ "${MANPATH}" = wolfCOSE ]; then \
         WOLFCOSE_REF="$(git -C wolfcose rev-parse HEAD)" make html V=${V}; \
+    elif [ "${MANPATH}" = wolfTPM ]; then \
+        WOLFTPM_REF="$(git -C wolftpm rev-parse HEAD)" make html V=${V}; \
     else \
         make html V=${V}; \
     fi

Makefile

@@ -5,7 +5,8 @@ endif
 
 # Handy debugging trick: `DOCKER_CMD_EXTRA_ARGS="--progress=plain" make` to see all the output
 WOLFCOSE_REF ?= main
-DOCKER_CMD=DOCKER_BUILDKIT=1 docker build $(DOCKER_CMD_EXTRA_ARGS) -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --build-arg V=$(V) --build-arg WOLFCOSE_REF=$(WOLFCOSE_REF) --target=manual --output=build -f Dockerfile .
+WOLFTPM_REF ?= master
+DOCKER_CMD=DOCKER_BUILDKIT=1 docker build $(DOCKER_CMD_EXTRA_ARGS) -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --build-arg V=$(V) --build-arg WOLFCOSE_REF=$(WOLFCOSE_REF) --build-arg WOLFTPM_REF=$(WOLFTPM_REF) --target=manual --output=build -f Dockerfile .
 
 all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfhsm wolfcose wolfengine wolfprovider fips-ready tuning porting faq fips-faq bc-migration
 
@@ -61,6 +62,10 @@ wolfssl-jni: build
 	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolftpm
+# Resolve a mutable ref (e.g. master) to an immutable commit so the Docker
+# build-arg cache key advances with upstream; a 40-char SHA passes through.
+# override so a command-line WOLFTPM_REF=<branch> is still resolved to a commit.
+wolftpm: override WOLFTPM_REF := $(shell r='$(WOLFTPM_REF)'; if printf '%s' "$$r" | grep -Eq '^[0-9a-f]{40}$$'; then printf '%s' "$$r"; else s=$$(git ls-remote https://github.com/wolfSSL/wolfTPM.git "$$r" 2>/dev/null | cut -f1); [ -n "$$s" ] && printf '%s' "$$s" || printf '%s' "$$r"; fi)
 wolftpm: MANPATH=wolfTPM
 wolftpm: PDFFILE=wolfTPM-Manual.pdf
 wolftpm: build

README.md

@@ -32,6 +32,14 @@ To rebuild from a specific commit, run `make wolfcose WOLFCOSE_REF=<commit>`.
 For unmerged local changes, run `make WOLFCOSE_SOURCE=/path/to/wolfCOSE` from
 the `wolfCOSE/` directory with the non-Docker build dependencies installed.
 
+The wolfTPM target works the same way. It reads manual pages from
+`wolfSSL/wolfTPM` `master` by default, from that repository's `docs/`
+directory, and prints the source commit used. To rebuild from a specific
+revision, run `make wolftpm WOLFTPM_REF=<ref>`, where `<ref>` is a branch, a
+tag, or a full 40 character commit SHA (abbreviated SHAs are not supported).
+For unmerged local changes, run `make WOLFTPM_SOURCE=/path/to/wolfTPM` from the
+`wolfTPM/` directory with the non-Docker build dependencies installed.
+
 ## Contributing
 
 There is a [CONTRIBUTING.md](CONTRIBUTING.md) document which outlines how to add manuals to the tree.

wolfTPM/.gitignore

@@ -0,0 +1,10 @@
+/build/
+/html/
+/src/
+/wolftpm/
+/api/
+/mkdocs.yml
+/header.txt
+/manual.generated.mk
+/wolfTPM-Manual.pdf
+/wolfTPM-Manual-jp.pdf

wolfTPM/Makefile

@@ -1,100 +1,56 @@
--include ../common/common.am
-.DEFAULT_GOAL := all
-
-all: pdf html
-
-
-SOURCES = chapter01.md \
-		  chapter02.md \
-		  chapter03.md \
-		  chapter04.md \
-		  chapter05.md \
-		  chapter06.md
+# The manual content and build adapter live in wolfSSL/wolfTPM.
+WOLFTPM_SOURCE ?= wolftpm
+WOLFTPM_REF ?= master
+export WOLFTPM_REF
 
+# The shared documentation build sets DOC_LANG=JA for the Japanese manual.
 ifeq ($(DOC_LANG),JA)
-	DOXY = Doxyfile-ja
-	PDF  = wolfTPM-Manual-jp.pdf
+LANG_ARG = --lang ja
 else
-	DOXY = Doxyfile
-	PDF  = wolfTPM-Manual.pdf
+LANG_ARG = --lang en
 endif
 
+.DEFAULT_GOAL := all
+.PHONY: all pdf html source
+all: source
+	python3 "$(WOLFTPM_SOURCE)/tools/docs_manual.py" build \
+		--documentation-root .. --source-root "$(WOLFTPM_SOURCE)" $(LANG_ARG) --target all
+
+source:
+	@set -eu; \
+	if [ "$(WOLFTPM_SOURCE)" = wolftpm ]; then \
+		if [ -e wolftpm ]; then \
+			if [ ! -e wolftpm/.git ]; then \
+				echo 'wolftpm exists but is not a Git checkout' >&2; exit 1; \
+			fi; \
+			remote=$$(git -C wolftpm config --get remote.origin.url) || { \
+				echo 'wolftpm has no origin remote' >&2; exit 1; \
+			}; \
+			if [ "$$remote" != https://github.com/wolfSSL/wolfTPM.git ]; then \
+				echo "wolftpm origin is $$remote; expected https://github.com/wolfSSL/wolfTPM.git" >&2; exit 1; \
+			fi; \
+			if [ -n "$$(git -C wolftpm status --porcelain)" ]; then \
+				echo 'wolftpm checkout has local changes; use WOLFTPM_SOURCE for local edits' >&2; exit 1; \
+			fi; \
+		else \
+			git init -q wolftpm; \
+			git -C wolftpm remote add origin https://github.com/wolfSSL/wolfTPM.git; \
+		fi; \
+		ref=$$WOLFTPM_REF; \
+		case "$$ref" in ''|-*) echo 'WOLFTPM_REF must be a commit, tag, or branch' >&2; exit 1;; esac; \
+		if printf '%s' "$$ref" | grep -Eq '^[0-9a-f]{40}$$' && \
+			git -C wolftpm cat-file -e "$$ref^{commit}" 2>/dev/null; then \
+			git -C wolftpm checkout --detach "$$ref"; \
+		else \
+			git -C wolftpm fetch --depth 1 origin "$$ref"; \
+			git -C wolftpm checkout --detach FETCH_HEAD; \
+		fi; \
+		echo "wolfTPM source: $$(git -C wolftpm rev-parse HEAD)"; \
+	else \
+		test -f "$(WOLFTPM_SOURCE)/tools/docs_manual.py"; \
+	fi
+
+pdf html: source
+	python3 "$(WOLFTPM_SOURCE)/tools/docs_manual.py" build \
+		--documentation-root .. --source-root "$(WOLFTPM_SOURCE)" $(LANG_ARG) --target $@
 
-wolftpm:
-	$(Q)git clone --depth 1 https://github.com/wolfSSL/wolfTPM wolftpm
-
-
-.PHONY: wolftpm-update
-wolftpm-update: wolftpm
-	$(Q)cd wolftpm && git pull --ff-only
-
-.PHONY: api
-api: wolftpm-update
-	$(Q)mkdir -p api/md
-	$(Q)cd wolftpm && doxygen docs/Doxyfile
-	$(Q)cd ..
-	$(Q)doxybook2 --input wolftpm/docs/xml --output api/md --config doxybook.cfg
-
-# Need an index.md, so let's make it chapter01.
-# Perl regex to fix two things:
-# 1. Doxybook2 replaces underscores with dashes in anchor tags (which breaks them)
-# 2. Remove leading slash on links so that mkdocs can parse them
-# 3. Fix the titles of the header files markdown
-.PHONY: html-prep
-html-prep: api
-  ifeq ($(DOC_LANG),JA)
-	$(Q)cp -a header-ja/group* build/html/
-	$(Q)cp -a header-ja/*8h* build/html/
-  else
-	$(Q)cp -a api/md/group* build/html/
-	$(Q)cp -a api/md/*8h* build/html/
-	$(Q)cp -a api/md/Classes build/html/
-	$(Q)perl -i -pe 's#\]\(/Classes/#](#g' build/html/Classes/*.md
-	$(Q)perl -i -pe "s/Classes\///g" build/html/Classes/*.md
-	$(Q)perl -i -pe 's#\]\(/#](../#g' build/html/Classes/*.md
-	$(Q)perl -i -pe 's#\]\(/#](#g' build/html/group* build/html/*8h*
-	$(Q)perl -i -pe "s/(\]\([^)#]*#[a-z]+-)([^)]+?)(\))/\$$1.(\$$2=~tr#-#_#r).\$$3/ge" build/html/group* build/html/*8h* build/html/Classes/*.md
-  endif
-
-	$(Q)rm -rf build/html/chapter05.md
-	$(Q)perl -i -pe "s/\/group_/group_/g" build/html/group* build/html/*8h*
-	$(Q)perl -i -pe "s/\/tpm2_/tpm2_/g" build/html/group* build/html/*8h*
-	$(Q)perl -i -pe "s/dox_comments\/header_files\///" build/html/*8h*
-
-# Set input format to gfm to fix issues with converted API docs
-# Regexes:
-# 1. Indent all headings by one #
-# 2. Fix broken anchors from Doxybook2
-# 3. Remove file references from links
-# 4. Three regexes to remove metadata which outputs in the PDF text
-# 5. Fix titles of the header files Markdown
-# 6. Two regexes to handle bad Doxygen that didn't convert and the LaTeX processor thinks is LaTeX commands
-# 7. For oversized enum table rows (>2000 chars), keep table formatting intact
-#    by splitting enum values across continuation rows to avoid LaTeX
-#    "Dimension too large" errors in longtable
-# NOTE: The final `cat` assembles the API Reference for the PDF from a hardcoded
-# list. It mirrors the "5. API Reference" nav in mkdocs.yml (which drives the
-# HTML build); the PDF build does not read that nav. Keep both lists in sync.
-.PHONY: pdf-prep
-pdf-prep: api
-	$(Q)perl -i -pe "s/# /## /g" api/md/*.md
-	$(Q)perl -i -pe "s/(\/group_.*|Classes\/struct.*|\/.*8h)\.md//g" api/md/*.md
-	$(Q)perl -i -pe "s/^-(-)+$$//" api/md/*.md
-	$(Q)perl -i -pe "s/^title:.*//" api/md/*.md
-	$(Q)perl -i -pe "s/^Updated on.*//" api/md/*.md
-	$(Q)perl -i -pe "s/^summary.*//" api/md/*.md
-	$(Q)perl -i -pe "s/dox_comments\/header_files\///" api/md/*.md
-	$(Q)perl -i -pe "s/^\\\\//" api/md/*.md
-	$(Q)perl -i -pe "s/\\\\par/par/g" api/md/*.md
-	$(Q)perl -i -pe "s/\[(.*?)\]\(Classes\/.*?.md\)/\[\1\]\(#typedef-\1\)/g" api/md/*.md
-	$(Q)perl -i -pe "s/(?<=md\#function\-)(.*)(?=\))/\$$1=~s#-#_#gr/ge" api/md/*.md
-	$(Q)perl -i -pe "s/(?<=md\#typedef\-)(.*)(?=\))/\$$1=~s#-#_#gr/ge" api/md/*.md
-	$(Q)perl -i -pe "s/(?<=md\#enum\-)(.*)(?=\))/\$$1=~s#-#_#gr/ge" api/md/*.md
-	$(Q)perl -i -pe 's!^\| enum\| (\*\*\[.*?\]\(.*?\)\*\*) \{(.*)\} \|\s*$$!do { my ($$name, $$vals) = ($$1, $$2); my @items = split(/, /, $$vals); my @chunks; my $$cur = ""; for my $$item (@items) { my $$cand = $$cur eq "" ? $$item : "$$cur, $$item"; if (length($$cand) > 220 && $$cur ne "") { push @chunks, $$cur; $$cur = $$item; } else { $$cur = $$cand; } } push @chunks, $$cur if $$cur ne ""; @chunks <= 1 ? "| enum| $$name { $$vals} |" : "| enum| $$name { $$chunks[0] |\n" . join("", map { "| | $$chunks[$$_]" . ($$_ == $$#chunks ? " }" : "") . " |\n" } 1..$$#chunks) }!ge if length > 2000' api/md/*.md
-	$(Q)rm -rf build/pdf/chapter05.md
-	$(Q)echo '# API Reference' >> build/pdf/chapter05.md
-  ifeq ($(DOC_LANG),JA)
-	$(Q)cat header-ja/group__TPM2__Proprietary.md header-ja/tpm2_8h.md header-ja/tpm2__wrap_8h.md header-ja/group__wolfTPM2__Wrappers.md >> build/pdf/chapter05.md
-  else
-	$(Q)cat api/md/group__TPM2__Proprietary.md api/md/tpm2_8h.md api/md/tpm2__wrap_8h.md api/md/tpm__io_8h.md api/md/group__wolfTPM2__Wrappers.md >> build/pdf/chapter05.md
-  endif