From 558802debcb0d9d7d22e905d938eabae199cf8a3 Mon Sep 17 00:00:00 2001 From: Brandon Mitchell Date: Wed, 9 Jul 2025 10:49:35 -0400 Subject: [PATCH] Docs: Update pandoc for rendering documentation The main reason for this is to fix the links in the output docs, which currently all 404. This upgrades pandoc to 3.1, which isn't the latest, due to a regression in the relative links between markdown files. I pulled out the "header.html" logic, injected the title directly, and configured the build to embed images into the output doc for better portability (and the ability to generate dev docs). Signed-off-by: Brandon Mitchell --- .tool/curver.go | 26 ++++++++++++++++++++++ .tool/genheader.go | 54 ---------------------------------------------- Makefile | 31 ++++++++++++-------------- 3 files changed, 40 insertions(+), 71 deletions(-) create mode 100644 .tool/curver.go delete mode 100644 .tool/genheader.go diff --git a/.tool/curver.go b/.tool/curver.go new file mode 100644 index 000000000..e4252cd79 --- /dev/null +++ b/.tool/curver.go @@ -0,0 +1,26 @@ +// Copyright 2025 The Linux Foundation +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package main + +import ( + "fmt" + + "github.com/opencontainers/image-spec/specs-go" +) + +// This package is intended to be executed using "go run .tool/curver.go". +func main() { + fmt.Println(specs.Version) +} diff --git a/.tool/genheader.go b/.tool/genheader.go deleted file mode 100644 index 6d1e1767d..000000000 --- a/.tool/genheader.go +++ /dev/null @@ -1,54 +0,0 @@ -// Copyright 2017 The Linux Foundation -// -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -package main - -import ( - "bytes" - "fmt" - "os" - "os/exec" - "strings" - "text/template" - - specs "github.com/opencontainers/image-spec/specs-go" -) - -var headerTemplate = template.Must(template.New("gen").Parse(`image-spec {{.Version}} -`)) - -type Obj struct { - Version string - Branch string -} - -func main() { - obj := Obj{ - Version: specs.Version, - Branch: specs.Version, - } - if strings.HasSuffix(specs.Version, "-dev") { - cmd := exec.Command("git", "log", "-1", `--pretty=%H`, "HEAD") - var out bytes.Buffer - cmd.Stdout = &out - cmd.Stderr = os.Stderr - if err := cmd.Run(); err != nil { - fmt.Fprintln(os.Stderr, err) - os.Exit(1) - } - - obj.Branch = strings.Trim(out.String(), " \n\r") - } - headerTemplate.Execute(os.Stdout, obj) -} diff --git a/Makefile b/Makefile index ef825617a..72cce275d 100644 --- a/Makefile +++ b/Makefile @@ -8,18 +8,17 @@ GOPATH:=$(shell go env GOPATH) OUTPUT_DIRNAME ?= output DOC_FILENAME ?= oci-image-spec -PANDOC_CONTAINER ?= ghcr.io/opencontainers/pandoc:2.9.2.1-8.fc33.x86_64@sha256:5d81ff930a043295a557be8b003ece2a33d14e91b28c50d368413b83372f8d28 +# pinned to a 3.1 release due to a regression, see https://github.com/jgm/pandoc/issues/10952 before upgrading +PANDOC_CONTAINER ?= docker.io/pandoc/latex:3.1@sha256:1cf54d9214a9b52de2f58cf5895cc596a5960711a54d7938dc72f2b23473caf3 ifeq "$(strip $(PANDOC))" '' ifneq "$(strip $(DOCKER))" '' PANDOC = $(DOCKER) run \ --rm \ - -v $(shell pwd)/:/input/:ro \ - -v $(shell pwd)/$(OUTPUT_DIRNAME)/:/$(OUTPUT_DIRNAME)/ \ - -u $(shell id -u) \ - --workdir /input \ + -v "$(CURDIR)/:/workdir/:ro" \ + -v "$(CURDIR)/$(OUTPUT_DIRNAME)/:/workdir/$(OUTPUT_DIRNAME)/" \ + -u "$(shell id -u):$(shell id -g)" \ + --workdir /workdir \ $(PANDOC_CONTAINER) - PANDOC_SRC := /input/ - PANDOC_DST := / endif endif @@ -55,24 +54,22 @@ fmt: ## format the json with indentation docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html ## generate a PDF/HTML version of the OCI image specification ifeq "$(strip $(PANDOC))" '' -$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) $(FIGURE_FILES) +$(OUTPUT_DIRNAME)/$(DOC_FILENAME).%: $(DOC_FILES) $(FIGURE_FILES) $(error cannot build $@ without either pandoc or docker) else $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) $(FIGURE_FILES) @mkdir -p $(OUTPUT_DIRNAME)/ && \ - $(PANDOC) -f gfm -t latex --pdf-engine=xelatex -V geometry:margin=0.5in,bottom=0.8in -V block-headings -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES)) - ls -sh $(realpath $@) + version="v$$(go run .tool/curver.go)" && \ + $(PANDOC) -f gfm -t latex -o $@ --metadata "title=image-spec $${version}" --standalone --file-scope --pdf-engine=xelatex -V geometry:margin=0.5in,bottom=0.8in -V block-headings $(DOC_FILES) + ls -sh $@ -$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: header.html $(DOC_FILES) $(FIGURE_FILES) +$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES) $(FIGURE_FILES) @mkdir -p $(OUTPUT_DIRNAME)/ && \ - cp -ap img/ $(shell pwd)/$(OUTPUT_DIRNAME)/&& \ - $(PANDOC) -f gfm -t html5 -H $(PANDOC_SRC)header.html --standalone -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES)) - ls -sh $(realpath $@) + version="v$$(go run .tool/curver.go)" && \ + $(PANDOC) -f gfm -t html5 -o $@ --metadata "title=image-spec $${version}" --standalone --file-scope --embed-resources -V "maxwidth:95%" $(DOC_FILES) + ls -sh $@ endif -header.html: .tool/genheader.go specs-go/version.go - go run .tool/genheader.go > $@ - .PHONY: validate-examples validate-examples: schema/schema.go ## validate examples in the specification markdown files cd schema && go test -run TestValidate .