Cleanup of build process

Cleaning up build, moving everything into /Makefile.
Every (versioned) bikeshed document should now have
STATUS, DATA, VERSION macros set and updated before publishing.
Old cruft is moved to /old for reference, to be cleanup up later.

Author: schuur

spec/LICENSE.md LICENSE.md

@@ -0,0 +1,75 @@
+# Build all documents and diagrams from spec/ into the build/ 
+# output folder. Please read RELEASE.md for more details on 
+# publishing the documents.
+#
+# Assumes python3 is installed
+# Assumes npm is installed
+#
+# Examples of usage:
+# make all
+#	make a clean build
+# make build
+#   build the documents and diagrams
+# make clean
+#   clean the build directory
+# make install
+# 	Will install bikeshed and mermaid-cli globally
+
+# spec/**.mmd -> build/**.svg
+DIAGRAMS := $(wildcard spec/v2/diagrams/*.mmd)
+DIAGRAMS := $(DIAGRAMS:spec/%.mmd=build/%.svg)
+SOURCES := $(wildcard **.bs)
+
+# Build rule for bikeshed documents
+build/%.html: spec/%.bs
+	@echo Check release status and version
+	$(eval status := $(shell sed -n 's/^Text Macro: STATUS //p' $<))
+	$(eval version := $(shell sed -n 's/^Text Macro: VERSION //p' $<))
+	$(eval date := $(shell sed -n 's/^Text Macro: DATE //p' $<))
+
+	@echo Build the document
+	mkdir -p $(dir $@)
+	bikeshed --allow-nonlocal-files spec $< $@
+
+	@echo Set the status in the document
+	@if [[ "$(status)" == "Release" ]]; then \
+		echo "Release: add version to title"; \
+		mv -f $@ [email protected]; \
+		sed 's/<title>\(.*\)<\/title>/<title>\1 (Version $(version))<\/title>/g' [email protected] > $@; \
+		mv -f $@ [email protected]; \
+		sed 's/\(<h1 .*id="title">.*\)\(<\/h1>\)/\1 (Version $(version))\2/g' [email protected] > $@; \
+	elif [[ "$(status)" == "Draft" || "$(status)" == "Consultation" ]]; then \
+		echo "No release: add version-date to title"; \
+		mv -f $@ [email protected]; \
+		sed 's/<title>\(.*\)<\/title>/<title>\1 (Version $(version)-$(date))<\/title>/g' [email protected] > $@; \
+		mv -f $@ [email protected]; \
+		sed 's/\(<h1 .*id="title">.*\)\(<\/h1>\)/\1 (Version $(version)-$(date))\2/g' [email protected] > $@; \
+	else \
+		echo "No status can be found"; \
+	fi
+	mv -f $@ [email protected]; \
+	sed 's/\(<h2 .*id="profile-and-date">\).*\(<\/h2>\)/\1$(status)\2/g' [email protected] > $@; \
+	rm -f [email protected];
+
+
+# Build rule for mermaid diagrams
+build/%.svg: spec/%.mmd
+	mkdir -p $(dir $@)
+	mmdc -i $< -o $@ --theme default
+
+all: clean build
+
+install:
+	@echo Install Bikeshed
+	pip3 install bikeshed && bikeshed update
+	@echo Install Mermaid
+	npm list -g @mermaid-js/mermaid-cli || npm install -g @mermaid-js/mermaid-cli
+
+clean:
+	rm -rf build
+
+build: \
+	build/index.html \
+	build/v2/index.html \
+	build/faq/index.html \
+	$(DIAGRAMS)

Makefile

@@ -1,4 +1,4 @@
-OUTDIR := upload
+OUTDIR := ../upload
 MMDC := ./node_modules/.bin/mmdc
 
 all: index.html
@@ -11,7 +11,7 @@ publish: index.html
 	cp $< $(OUTDIR)
 
 index.html: index.bs $(DIAGRAMS)
-	bikeshed spec $< $@
+	bikeshed --allow-nonlocal-files spec $< $@ 
 
 serve:
 	bikeshed serve index.bs

spec/RELEASE.md RELEASE.md

@@ -1,4 +1,4 @@
-OUTDIR := ../upload/faq
+OUTDIR := ../../upload/faq
 
 all: index.html
 

spec/Makefile old/Makefile

@@ -16,7 +16,7 @@ publish: index.html computed-metadata.include
 	cp $^ $(OUTDIR)
 
 index.html: index.bs $(DIAGRAMS)
-	bikeshed spec $< $@ --md-text-macro="$(STATUS)"
+	bikeshed --allow-nonlocal-files spec $< $@ --md-text-macro="$(STATUS)"
 
 %.svg: %.mmd
 	mmdc -i $< -o $@

spec/faq/Makefile old/faq/Makefile

@@ -11,7 +11,6 @@ Abstract: This document provides Frequently Asked Questions for PACT Technical S
 Repository: wbcsd/data-exchange-protocol
 Markup Shorthands: markdown yes, idl yes, dfn yes
 Boilerplate: omit copyright, omit conformance
-
 </pre>
 
 # Frequently Asked Questions # {#faqs}

spec/header.include old/header.include

@@ -1,9 +1,11 @@
 <pre class='metadata'>
-Title: Technical Specifications for PCF Data Exchange
+Text Macro: DATE 20230201
 Text Macro: VERSION 1.0.1
-Shortname: data-exchange-protocol
+Text Macro: STATUS Release
+Title: Technical Specifications for PCF Data Exchange
 Level: 1
 Status: LD
+Shortname: data-exchange-protocol
 TR: https://wbcsd.github.io/tr/2023/data-exchange-protocol-20230201/
 Mailing List: [email protected]
 Editor:
@@ -1384,5 +1386,5 @@ highlight: json
 # Appendix A: License # {#license}
 
 <pre class=include>
-path: LICENSE.md
+path: ../LICENSE.md
 </pre>

spec/release.sh old/release.sh

@@ -1,9 +1,23 @@
+<!-- 
+Before publishing, make sure to: 
+ - Add an entry to Changelog
+ - Update the DATE below
+ - STATUS can be Draft|Consultation|Release
+In addition, for publishing a release:
+  Set STATUS Release
+  Update VERSION major.minor.patch
+  Update the Previous Version and TR links
+-->
 <pre class='metadata'>
-Title: Technical Specifications for PCF Data Exchange
+Text Macro: DATE 20241024
 Text Macro: VERSION 2.3.0
-Shortname: data-exchange-protocol
+Text Macro: STATUS Draft
+Title: Technical Specifications for PCF Data Exchange
+TR: https://wbcsd.github.io/tr/2024/data-exchange-protocol-20241024/
+Previous Version: https://wbcsd.github.io/tr/2024/data-exchange-protocol-20240410/
 Level: 1
 Status: LD
+Shortname: data-exchange-protocol
 Mailing List: [email protected]
 Editor: Gertjan Schuurmans (WBCSD), https://www.wbcsd.org, [email protected]
 Former Editor: Beth Hadley (WBCSD), https://www.wbcsd.org, [email protected]
@@ -14,7 +28,6 @@ Abstract: This document specifies a data model for GHG emission data at product
 Markup Shorthands: markdown yes, idl yes, dfn yes
 Boilerplate: omit copyright, omit conformance
 Local Boilerplate: header yes
-Local Boilerplate: computed-metadata yes
 Metadata Include: This version off
 </pre>
 
@@ -2792,7 +2805,7 @@ highlight: json
 # Appendix A: License # {#license}
 
 <pre class=include>
-path: LICENSE.md
+path: ../../LICENSE.md
 </pre>
 
 # Appendix B: Changelog # {#changelog}