output documentation

This carries over the efforts from image-spec and runtime-spec to make
output documentation (PDF and HTML).

Also assumes a version of v0.1.0-dev for now.

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

.gitignore

@@ -0,0 +1,2 @@
+output
+header.html

.tool/genheader.go

@@ -0,0 +1,54 @@
+// Copyright 2018 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"
+
+	distspec "github.com/opencontainers/distribution-spec"
+)
+
+var headerTemplate = template.Must(template.New("gen").Parse(`<title>distribution-spec {{.Version}}</title>
+<base href="https://raw.githubusercontent.com/opencontainers/distribution-spec/{{.Branch}}/">`))
+
+type Obj struct {
+	Version string
+	Branch  string
+}
+
+func main() {
+	obj := Obj{
+		Version: distspec.Version,
+		Branch:  distspec.Version,
+	}
+	if strings.HasSuffix(distspec.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)
+}

Makefile

@@ -1,5 +1,30 @@
 EPOCH_TEST_COMMIT	:= 91d6d8466e68f1efff7977b63ad6f48e72245e05
 
+DOCKER		?= $(shell command -v docker 2>/dev/null)
+PANDOC		?= $(shell command -v pandoc 2>/dev/null)
+
+OUTPUT_DIRNAME	?= output/
+DOC_FILENAME	?= oci-distribution-spec
+
+PANDOC_CONTAINER ?= docker.io/vbatts/pandoc:1.19.1-3.fc27.x86_64
+ifeq "$(strip $(PANDOC))" ''
+	ifneq "$(strip $(DOCKER))" ''
+		PANDOC = $(DOCKER) run \
+			-it \
+			--rm \
+			-v $(shell pwd)/:/input/:ro \
+			-v $(shell pwd)/$(OUTPUT_DIRNAME)/:/$(OUTPUT_DIRNAME)/ \
+			-u $(shell id -u) \
+			--workdir /input \
+			$(PANDOC_CONTAINER)
+		PANDOC_SRC := /input/
+		PANDOC_DST := /
+	endif
+endif
+
+DOC_FILES	:= spec.md
+FIGURE_FILES	:=
+
 test: .gitvalidation
 
 # When this is running in travis, it will only check the travis commit range
@@ -11,6 +36,27 @@ else
 	git-validation -v -run DCO,short-subject,dangling-whitespace -range $(EPOCH_TEST_COMMIT)..HEAD
 endif
 
+docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html
+
+ifeq "$(strip $(PANDOC))" ''
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(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 markdown_github -t latex --latex-engine=xelatex -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
+	ls -sh $(realpath $@)
+
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: header.html $(DOC_FILES) $(FIGURE_FILES)
+	mkdir -p $(OUTPUT_DIRNAME)/ && \
+	cp -ap img/ $(shell pwd)/$(OUTPUT_DIRNAME)/&& \
+	$(PANDOC) -f markdown_github -t html5 -H $(PANDOC_SRC)header.html --standalone -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
+	ls -sh $(realpath $@)
+endif
+
+header.html: .tool/genheader.go version.go
+	go run .tool/genheader.go > $@
+
 install.tools: .install.gitvalidation
 
 .install.gitvalidation:

version.go

@@ -0,0 +1,32 @@
+// Copyright 2018 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 distspec
+
+import "fmt"
+
+const (
+	// VersionMajor is for an API incompatible changes
+	VersionMajor = 0
+	// VersionMinor is for functionality in a backwards-compatible manner
+	VersionMinor = 1
+	// VersionPatch is for backwards-compatible bug fixes
+	VersionPatch = 0
+
+	// VersionDev indicates development branch. Releases will be empty string.
+	VersionDev = "-dev"
+)
+
+// Version is the specification version that the package types support.
+var Version = fmt.Sprintf("%d.%d.%d%s", VersionMajor, VersionMinor, VersionPatch, VersionDev)