Refactor build gh-action to use Makefile and embed images into HTML document

.github/workflows/adoc_build.yml

@@ -21,6 +21,8 @@
 #
 name: Asciidoctor Build Workflow
 on:
+  # manually run workflow
+  workflow_dispatch:
   # trigger on PR event against main (will not run publish job)
   pull_request:
     branches: [ main ]
@@ -40,7 +42,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     # Check out PR
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     # Create build directory
     - run: mkdir conventions_build
     - name: Set draft date-time formatting
@@ -55,7 +57,7 @@ jobs:
     - name: Build cf-conventions.html
       uses: Analog-inc/[email protected]
       with:
-        shellcommand: 'asciidoctor --verbose ${FINAL_TAG} -a docprodtime=$(date -u ${DATE_FMT}) cf-conventions.adoc -D conventions_build; cp -r images conventions_build'
+        shellcommand: 'asciidoctor --verbose ${FINAL_TAG} -a docprodtime=$(date -u ${DATE_FMT}) -a data-uri cf-conventions.adoc -D conventions_build'
     # Patch the cfconventions.org link
     - run: sed -E -i 's+(See&#160;)(https://cfconventions.org)(&#160;for&#160;further&#160;information.)+\1<a href="\2" target="_blank">\2</a>\3+' ./conventions_build/cf-conventions.html
     # Build cf-conventions.pdf using the Analog-inc asciidoctor-action
@@ -65,7 +67,7 @@ jobs:
         shellcommand: 'asciidoctor-pdf --verbose ${FINAL_TAG} -a docprodtime=$(date -u ${DATE_FMT}) -d book -a pdf-theme=default-theme-CF-version.yml --trace cf-conventions.adoc -D conventions_build'
     # Upload artifact containing cf-conventions.html, cf-conventions.pdf
     - name: Upload cf-conventions doc preview
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: conventions_docs
         path: conventions_build/
@@ -75,7 +77,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     # Checkout PR
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     # Create build directory
     - run: mkdir conformance_build
     - name: Set "final" tag
@@ -94,27 +96,11 @@ jobs:
         shellcommand: 'asciidoctor-pdf --verbose ${FINAL_TAG} -d book conformance.adoc -D conformance_build'
     # Upload artifact containing conformance.html, conformance.pdf
     - name: Upload conformance doc preview
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: conformance_docs
         path: conformance_build/
 
-  # Job to an artifact of the images/ directory.
-  # Only needed if we are going to run the publish job.
-  images_artifact:
-    name: Create artifact of image directory
-    if: github.event_name != 'pull_request'
-    runs-on: ubuntu-latest
-    steps:
-    # Checkout ref
-    - uses: actions/checkout@v3
-    # Create the image_directory artifact
-    - name: Upload images directory
-      uses: actions/upload-artifact@v3
-      with:
-        name: image_directory
-        path: images/
-
   # Use artifacts from the build_conventions, build_conformance, and
   # images_artifact jobs to update the gh-pages branch. The location of the
   # files to be updated depend on whether the job it triggered from a PR merge
@@ -126,11 +112,11 @@ jobs:
     # Do not run on pull requests
     if: github.event_name != 'pull_request'
     # Wait for the build artifacts to become available
-    needs: [build_conventions, build_conformance, images_artifact]
+    needs: [build_conventions, build_conformance]
     runs-on: ubuntu-latest
     steps:
       # Checkout gh-pages branch
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: 'gh-pages'
       # Will new docs go into root, or into a directory named after the
@@ -145,7 +131,7 @@ jobs:
           fi
       # Obtain the build artifacts from the previous jobs and place them in the
       # build/ directory
-      - uses: actions/download-artifact@v3
+      - uses: actions/download-artifact@v4
         with:
           path: build/
       # If we are doing a release, we need to create the release directory
@@ -157,8 +143,6 @@ jobs:
       - name: Remove old images directory
         if: github.event_name != 'release'
         run: rm -rf ${{ env.TARGET_DIR }}/images
-      - name: Move images directory to target directory
-        run: mv build/image_directory ${{ env.TARGET_DIR }}/images
       - name: Copy conventions and conformance documents
         run: |
           cp build/conventions_docs/cf-conventions.html ${{ env.TARGET_DIR }}/

.gitignore

@@ -4,3 +4,8 @@
 # Do not store generated HTML and PDF files
 cf-conventions.html
 cf-conventions.pdf
+conventions_build/
+conformance.html
+conformance.pdf
+conformance_build/
+.vscode/

Makefile

@@ -0,0 +1,62 @@
+MAIN_DOC := cf-conventions
+MAIN_DOC_BUILD_DIR := ./conventions_build
+
+MAIN_DOC_INC := version toc-extra 
+MAIN_DOC_INC += ch01 ch02 ch03 ch04 ch05 ch06 ch07 ch08 ch09
+MAIN_DOC_INC += appa appb appc appd appe appf appg apph appi appj appk
+MAIN_DOC_INC += history bibliography
+
+MAIN_DOC_IMG := NFFFFFF-1.0.png
+MAIN_DOC_IMG += ci_1d_interpolation_subarea.svg ci_2d_interpolation_subarea.svg ci_bounds_interpolation.svg
+MAIN_DOC_IMG += ci_dimensions_overview.svg ci_interpolation_coefficients.svg ci_interpolation_subarea_generation_process.svg
+MAIN_DOC_IMG += ci_quadratic1.svg ci_quadratic2.svg ci_quadratic3.svg mesh_figure.svg
+
+MAIN_DOC_IMG_BLD := cfdm_cf_concepts.svg cfdm_coordinate_reference.svg cfdm_coordinates.svg cfdm_field.svg
+MAIN_DOC_IMG_BLD += order_horizontal_bounds__1D_coord_variables.png order_horizontal_bounds__2D_coord_variables.png
+
+MAIN_DOC_IMG += $(MAIN_DOC_IMG_BLD)
+
+CONF_DOC := conformance
+CONF_DOC_BUILD_DIR := ./conformance_build
+CONF_DOC_INC := version
+
+
+
+.PHONY: all clean
+all: $(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).html $(addpreffix images/, $(MAIN_DOC_IMG_BLD)) $(CONF_DOC_BUILD_DIR)/$(CONF_DOC).html $(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).pdf
+
+$(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).html: $(MAIN_DOC).adoc $(addprefix images/, $(MAIN_DOC_IMG)) $(addsuffix .adoc, $(MAIN_DOC_INC)) | $(MAIN_DOC_BUILD_DIR)
+	asciidoctor --verbose ${FINAL_TAG} -a data-uri -a docprodtime=$(date -u ${DATE_FMT}) $(MAIN_DOC).adoc -D $(MAIN_DOC_BUILD_DIR)
+
+$(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).pdf: $(MAIN_DOC).adoc $(addprefix images/, $(MAIN_DOC_IMG)) $(addsuffix .adoc, $(MAIN_DOC_INC)) | $(MAIN_DOC_BUILD_DIR)
+	asciidoctor-pdf --verbose ${FINAL_TAG} -a docprodtime=$(date -u ${DATE_FMT}) -d book -a pdf-theme=default-theme-CF-version.yml --trace $(MAIN_DOC).adoc -D $(MAIN_DOC_BUILD_DIR)
+
+$(CONF_DOC_BUILD_DIR)/$(CONF_DOC).html: $(CONF_DOC).adoc $(addsuffix .adoc, $(CONF_DOC_INC)) | $(CONF_DOC_BUILD_DIR)
+	asciidoctor --verbose ${FINAL_TAG} $(CONF_DOC).adoc -D $(CONF_DOC_BUILD_DIR)
+
+$(MAIN_DOC_BUILD_DIR):
+	mkdir -vp $(MAIN_DOC_BUILD_DIR)
+
+$(CONF_DOC_BUILD_DIR):
+	mkdir -vp $(CONF_DOC_BUILD_DIR)
+
+clean:
+	rm -rvf $(MAIN_DOC_BUILD_DIR)
+
+images/cfdm_cf_concepts.svg: images/cfdm_cf_concepts.gv
+	dot -Tsvg $< -o $@
+
+images/cfdm_coordinate_reference.svg: images/cfdm_coordinate_reference.gv
+	dot -Tsvg $< -o $@
+
+images/cfdm_coordinates.svg: images/cfdm_coordinates.gv
+	dot -Tsvg $< -o $@
+
+images/cfdm_field.svg: images/cfdm_field.gv
+	dot -Tsvg $< -o $@
+
+images/order_horizontal_bounds__1D_coord_variables.png: images/order_horizontal_bounds__1D_coord_variables.pdf
+	pdftoppm -progress -singlefile -r 300 -png $< $(basename $@)
+
+images/order_horizontal_bounds__2D_coord_variables.png: images/order_horizontal_bounds__2D_coord_variables.pdf
+	pdftoppm -progress -singlefile -r 300 -png $< $(basename $@)

appd.adoc

@@ -361,7 +361,7 @@ No `standard_name` has been defined for `z1`, `z2`, `a`, `href` or `k_c`.
 // and put the table immediately thereafter, with its own title:
 [[table-computed-standard-names]]
 .Consistent sets of values for the standard_names of formula terms and the computed_standard_name needed in defining the ocean sigma coordinate, the ocean s-coordinate, the ocean_sigma over z coordinate, and the ocean double sigma coordinate.
-image::NFFFFFF-1.0.png[caption=""]
+image::images/NFFFFFF-1.0.png[caption=""]
 
 [options="header",cols="1,3,2,3",caption="Table D.1. "]
 |===============