Merge pull request #131 from aidangarske/wolfhsm-docs

wolfHSM Manual (migration from wolfHSM-docs to wolfssl/documentation)
wolfSSL · Jun 6, 2024 · 7570a07 · 7570a07
2 parents 8ea2a66 + 661d5d9
commit 7570a07
Show file tree

Hide file tree

Showing 35 changed files with 4,442 additions and 158 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,5 @@ wolfSSL/api/
 wolfSSL/wolfssl/
 wolfTPM/api/
 wolfTPM/wolftpm/
+wolfHSM/api
+wolfHSM/docs/xml
diff --git a/Dockerfile b/Dockerfile
@@ -14,9 +14,9 @@ RUN apt-get -y install pandoc mkdocs doxygen git build-essential cmake libfmt-de
 RUN git clone --depth=1 https://github.com/pantor/inja
 RUN cd inja && cmake . -DBUILD_TESTING=OFF -DBUILD_BENCHMARK=OFF && make install
 
-RUN git clone https://github.com/matusnovak/doxybook2
+RUN git clone https://github.com/dgarske/doxybook2
 # Checkout to working version of doxybook2
-RUN cd doxybook2 && git checkout 187dc2991dabe65f808263
+RUN cd doxybook2 && git checkout master
 RUN cd doxybook2 && cmake . && make install
 # Copy the source files into Docker, this and any subsequent steps won't be cached
 WORKDIR /src/wolfssl
@@ -26,15 +26,17 @@ COPY . .
 FROM builder AS wolfssl-stage1
 ARG MANPATH
 ARG PDFFILE
+ARG V
 WORKDIR /src/wolfssl/${MANPATH}
-RUN make pdf
+RUN make pdf V=${V}
 
 # Build wolfSSL HTML
 FROM wolfssl-stage1 AS wolfssl-stage2
 ARG MANPATH
 ARG PDFFILE
+ARG V
 WORKDIR /src/wolfssl/${MANPATH}
-RUN make html
+RUN make html V=${V}
 
 # Build both wolfSSL HTML and PDF
 FROM scratch AS manual

diff --git a/Makefile b/Makefile
@@ -1,81 +1,92 @@
-DOCKER_CMD=DOCKER_BUILDKIT=1 docker build -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --target=manual --output=build -f Dockerfile .
+Q?=@
+ifeq ($(V),1)
+  Q=
+endif
 
-all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfengine fips-ready tuning porting
+DOCKER_CMD=DOCKER_BUILDKIT=1 docker build -t doc_build --build-arg MANPATH=$(MANPATH) --build-arg PDFFILE=$(PDFFILE) --build-arg V=$(V) --target=manual --output=build -f Dockerfile .
+
+all: wolfssl wolfssh wolfboot wolfclu wolfcrypt-jni wolfmqtt wolfsentry wolfssl-jni wolftpm wolfhsm wolfengine fips-ready tuning porting
 
 build:
-	@mkdir -p build
+	$(Q)mkdir -p build
 
 .PHONY: wolfssl
 wolfssl: MANPATH=wolfSSL
 wolfssl: PDFFILE=wolfSSL-Manual.pdf
 wolfssl: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolfssh
 wolfssh: MANPATH=wolfSSH
 wolfssh: PDFFILE=wolfSSH-Manual.pdf
 wolfssh: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolfboot
 wolfboot: MANPATH=wolfBoot
 wolfboot: PDFFILE=wolfBoot-Manual.pdf
 wolfboot: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolfclu
 wolfclu: MANPATH=wolfCLU
 wolfclu: PDFFILE=wolfCLU-Manual.pdf
 wolfclu: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolfcrypt-jni
 wolfcrypt-jni: MANPATH=wolfCrypt-JNI
 wolfcrypt-jni: PDFFILE=wolfCrypt-JNI-JCE-Manual.pdf
 wolfcrypt-jni: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolfmqtt
 wolfmqtt: MANPATH=wolfMQTT
 wolfmqtt: PDFFILE=/wolfMQTT-Manual.pdf
 wolfmqtt: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolfsentry
 wolfsentry: MANPATH=wolfSentry
 wolfsentry: PDFFILE=wolfSentry-Manual.pdf
 wolfsentry: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolfssl-jni
 wolfssl-jni: MANPATH=wolfSSL-JNI
 wolfssl-jni: PDFFILE=wolfSSL-JNI-JSSE-Manual.pdf
 wolfssl-jni: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolftpm
 wolftpm: MANPATH=wolfTPM
 wolftpm: PDFFILE=wolfTPM-Manual.pdf
 wolftpm: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
+
+.PHONY: wolfhsm
+wolfhsm: MANPATH=wolfHSM
+wolfhsm: PDFFILE=wolfHSM-Manual.pdf
+wolfhsm: build
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: wolfengine
 wolfengine: MANPATH=wolfEngine
 wolfengine: PDFFILE=wolfEngine-Manual.pdf
 wolfengine: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: porting
 porting: MANPATH=wolfSSL-Porting
 porting: PDFFILE=wolfSSL-Porting-Guide.pdf
 porting: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: fips-ready
 fips-ready: MANPATH=wolfSSL-FIPS-Ready
 fips-ready: PDFFILE=wolfSSL-FIPS-Ready.pdf
 fips-ready: build
-	@$(DOCKER_CMD)
+	$(Q)$(DOCKER_CMD)
 
 .PHONY: tuning
 tuning: MANPATH=wolfSSL-Tuning
@@ -84,4 +95,4 @@ tuning: build
 	@$(DOCKER_CMD)
 
 clean:
-	rm -rf build
+	$(Q)rm -rf build
diff --git a/common/common.am b/common/common.am
@@ -1,5 +1,10 @@
 # vim: ft=automake
 
+Q?=@
+ifeq ($(V),1)
+  Q=
+endif
+
 HTML = html/
 
 ifeq ($(DOC_LANG),JA)
@@ -16,35 +21,35 @@ endif
 
 .PHONY: builddir
 builddir:
-	@mkdir -p build/pdf
-	@mkdir -p build/html
+	$(Q)mkdir -p build/pdf
+	$(Q)mkdir -p build/html
 
 .PHONY: html-setup
 html-setup:
-	@git submodule update --init
-	-cd ../mkdocs-material; patch -p1  < $(PATCH) --ignore-whitespace -N
-	@cp -a $(SRC)/* build/html/
-	@cp ../common/*.png build/html/
-	@cp ../common/*.css build/html/
-	@perl -i -pe 's/    ```/```/g' build/html/*.md
-	@perl -i -pe "s/\#--/\#-/g" build/html/*.md
-	@mv build/html/$(word 1,$(SOURCES)) build/html/index.md
+	$(Q)git submodule update --init
+	-cd ../mkdocs-material; patch -p1 < $(PATCH) --ignore-whitespace -N
+	$(Q)cp -a $(SRC)/* build/html/
+	$(Q)cp ../common/*.png build/html/
+	$(Q)cp ../common/*.css build/html/
+	$(Q)perl -i -pe 's/    ```/```/g' build/html/*.md
+	$(Q)perl -i -pe "s/\#--/\#-/g" build/html/*.md
+	$(Q)mv build/html/$(word 1,$(SOURCES)) build/html/index.md
 
 .PHONY: html
 html: builddir html-setup html-prep
-	@mkdir -p html
-	@mkdocs build -f $(MKDOC)
+	$(Q)mkdir -p html
+	$(Q)mkdocs build -f $(MKDOC)
 
 .PHONY: pdf-setup
 pdf-setup: builddir
-	@cp -a $(SRC)/* build/pdf/
-	@cp ../common/*.png build/pdf/
-	@perl -i -pe "s/chapter[0-9][0-9].md|appendix[0-9][0-9].md//g" build/pdf/*.md
-	@perl -i -pe "s/\#--/\#/g" build/pdf/*.md
+	$(Q)cp -a $(SRC)/* build/pdf/
+	$(Q)cp ../common/*.png build/pdf/
+	$(Q)perl -i -pe "s/chapter[0-9][0-9].md|appendix[0-9][0-9].md//g" build/pdf/*.md
+	$(Q)perl -i -pe "s/\#--/\#/g" build/pdf/*.md
 
 .PHONY: pdf
 pdf: pdf-setup pdf-prep
-	@cd build/pdf && pandoc \
+	$(Q)cd build/pdf && pandoc \
 		-N \
 		-s \
 		--metadata date="`date -I`" \
@@ -63,16 +68,16 @@ pdf: pdf-setup pdf-prep
 
 .PHONY: serve
 serve: builddir html-setup html-prep
-	@mkdocs serve
+	$(Q)mkdocs serve
 
 .PHONY: linkcheck
 linkcheck:
-	@$(foreach source_md,$(SOURCES),docker run -v ${CURDIR}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable --config /tmp/test/linkcheck.json /tmp/src/$(source_md) || exit;)
-	@$(foreach source_md,$(APPENDIX),docker run -v ${CURDIR}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable --config /tmp/test/linkcheck.json /tmp/src/$(source_md) || exit;)
+	$(Q)$(foreach source_md,$(SOURCES),docker run -v ${CURDIR}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable --config /tmp/test/linkcheck.json /tmp/src/$(source_md) || exit;)
+	$(Q)$(foreach source_md,$(APPENDIX),docker run -v ${CURDIR}:/tmp:ro --rm -i ghcr.io/tcort/markdown-link-check:stable --config /tmp/test/linkcheck.json /tmp/src/$(source_md) || exit;)
 
 .PHONY: lintcheck
 lintcheck:
-	@docker run -i --rm -v  ${CURDIR}:/work tmknom/markdownlint -c /work/test/lintcheck.json /work/src
+	$(Q)docker run -i --rm -v  ${CURDIR}:/work tmknom/markdownlint -c /work/test/lintcheck.json /work/src
 
 .PHONY: test
 test: lintcheck linkcheck

diff --git a/wolfBoot/header.txt b/wolfBoot/header.txt
@@ -8,7 +8,7 @@ header-includes:
     # Fancy page headers
     - \usepackage{fancyhdr}
     - \pagestyle{fancy}
-    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2021 wolfSSL Inc.}
+    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2024 wolfSSL Inc.}
     # Wrap long syntax highlighting code blocks
     - \usepackage{fvextra}
     - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}

diff --git a/wolfCLU/header.txt b/wolfCLU/header.txt
@@ -8,7 +8,7 @@ header-includes:
     # Fancy page headers
     - \usepackage{fancyhdr}
     - \pagestyle{fancy}
-    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2022 wolfSSL Inc.}
+    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2024 wolfSSL Inc.}
     # Wrap long syntax highlighting code blocks
     - \usepackage{fvextra}
     - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}

diff --git a/wolfCrypt-JNI/header.txt b/wolfCrypt-JNI/header.txt
@@ -8,7 +8,7 @@ header-includes:
     # Fancy page headers
     - \usepackage{fancyhdr}
     - \pagestyle{fancy}
-    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2021 wolfSSL Inc.}
+    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2024 wolfSSL Inc.}
     # Wrap long syntax highlighting code blocks
     - \usepackage{fvextra}
     - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}

diff --git a/wolfEngine/header.txt b/wolfEngine/header.txt
@@ -8,7 +8,7 @@ header-includes:
     # Fancy page headers
     - \usepackage{fancyhdr}
     - \pagestyle{fancy}
-    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2022 wolfSSL Inc.}
+    - \fancyfoot[LO,RE]{COPYRIGHT \copyright 2024 wolfSSL Inc.}
     # Wrap long syntax highlighting code blocks
     - \usepackage{fvextra}
     - \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}