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,32 +42,25 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     # Check out PR
-    - uses: actions/checkout@v3
-    # Create build directory
-    - run: mkdir conventions_build
-    - name: Set draft date-time formatting
-      if: github.event_name != 'release'
-      run: |
-        echo "DATE_FMT=+%d %B, %Y %H:%M:%SZ" >> "$GITHUB_ENV"
-    - name: Set "final" tag and date-time formatting
+    - uses: actions/checkout@v4
+    # If it is release event, tag for final
+    - name: If it is a release add the "final" tag and date timestamp formatting
       if: github.event_name == 'release'
       run: |
-        echo "FINAL_TAG=-a final" >> "$GITHUB_ENV"; echo "DATE_FMT=+%d %B, %Y" >> "$GITHUB_ENV"
+        echo "CF_FINAL=True" >> "$GITHUB_ENV"
     # Build cf-conventions.html using the Analog-inc asciidoctor-action
     - name: Build cf-conventions.html
-      uses: Analog-inc/asciidoctor-action@v1.2
+      uses: Analog-inc/asciidoctor-action@v1
       with:
-        shellcommand: 'asciidoctor --verbose ${FINAL_TAG} -a docprodtime=$(date -u ${DATE_FMT}) cf-conventions.adoc -D conventions_build; cp -r images 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
+        shellcommand: 'make conventions-html'
     # Build cf-conventions.pdf using the Analog-inc asciidoctor-action
     - name: Build cf-conventions.pdf
-      uses: Analog-inc/asciidoctor-action@v1.2
+      uses: Analog-inc/asciidoctor-action@v1
       with:
-        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'
+        shellcommand: 'make conventions-pdf'
     # Upload artifact containing cf-conventions.html, cf-conventions.pdf
-    - name: Upload cf-conventions doc preview
-      uses: actions/upload-artifact@v3
+    - name: Save cf-conventions doc preview
+      uses: actions/upload-artifact@v4
       with:
         name: conventions_docs
         path: conventions_build/
@@ -75,46 +70,31 @@ 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
+    # If it is release event, tag for final
+    - name: If it is a release add the "final" tag and date timestamp formatting
       if: github.event_name == 'release'
       run: |
-        echo "FINAL_TAG=-a final" >> "$GITHUB_ENV"
+        echo "CF_FINAL=True" >> "$GITHUB_ENV"
     # Build conformance.html using the Analog-inc asciidoctor-action
     - name: Build conformance.html
-      uses: Analog-inc/asciidoctor-action@v1.2
+      uses: Analog-inc/asciidoctor-action@v1
       with:
-        shellcommand: 'asciidoctor --verbose ${FINAL_TAG} conformance.adoc -D conformance_build'
+        shellcommand: 'make conformance-html'
     # Build conformance.pdf using the Analog-inc asciidoctor-action
     - name: Build conformance.pdf
-      uses: Analog-inc/asciidoctor-action@v1.2
+      uses: Analog-inc/asciidoctor-action@v1
       with:
-        shellcommand: 'asciidoctor-pdf --verbose ${FINAL_TAG} -d book conformance.adoc -D conformance_build'
+        shellcommand: 'make conformance-pdf'
     # Upload artifact containing conformance.html, conformance.pdf
-    - name: Upload conformance doc preview
-      uses: actions/upload-artifact@v3
+    - name: Save conformance doc preview
+      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 +106,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 +125,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 +137,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/

.zenodo.json

@@ -157,7 +157,7 @@
     {"name": "Philip Cameron-Smith", "affiliation": "LLNL"},
     {"name": "John Caron", "affiliation": "Unidata"},
     {"name": "Guilherme Castelão", "affiliation": "Scripps Institution of Oceanography, UC San Diego", "orcid": "0000-0002-6765-0708"},
-    {"name": "Antonio Cofi\u00f1o", "affiliation": "University of Cantabria"},
+    {"name": "Antonio S. Cofi\u00f1o", "affiliation": "Institute of Physics of Cantabria, CSIC-UC", "orcid": "0000-0001-7719-979X"},
     {"name": "Lorenzo Corgnati", "affiliation": "CNR-ISMAR"},
     {"name": "Ethan Davis", "affiliation": "NSF Unidata", "orcid": "0000-0002-8530-2213"},
     {"name": "Cecelia DeLuca", "affiliation": "NOAA"},

Makefile

@@ -0,0 +1,97 @@
+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_INC := $(addsuffix .adoc, $(MAIN_DOC_INC))
+
+#These are the static files for the images of the conventions document
+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
+
+#  ... and th list of dynamic files images, with a build rule that appears below
+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)
+
+MAIN_DOC_IMG := $(addprefix images/, $(MAIN_DOC_IMG))
+
+CONF_DOC := conformance
+
+CONF_DOC_BUILD_DIR := conformance_build
+
+CONF_DOC_INC := conformance.adoc version.adoc
+
+ifdef CF_FINAL
+DATE_FORMAT := +%d&\#160;%B,&\#160;%Y
+FINAL_TAG := -a final
+else
+DATE_FORMAT ?= +%d&\#160;%B,&\#160;%Y&\#160;%H:%M:%SZ
+FINAL_TAG ?= -a draft
+endif
+
+DATE_DOCPROD != LC_ALL=C date -u "$(DATE_FORMAT)"
+
+.PHONY: all clean images html pdf conventions-html conventions-pdf conventions conformance-html conformance-pdf conformance
+all: images html pdf 
+images: $(addprefix images/, $(MAIN_DOC_IMG_BLD)) 
+
+conventions-html: $(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).html
+conventions-pdf: $(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).pdf
+conventions: conventions-html conventions-pdf
+
+conformance-html: $(CONF_DOC_BUILD_DIR)/$(CONF_DOC).html
+conformance-pdf: $(CONF_DOC_BUILD_DIR)/$(CONF_DOC).pdf
+conformance: conformance-html conformance-pdf
+
+html: conventions-html conformance-html
+pdf: conventions-pdf conformance-pdf
+
+$(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).html: $(MAIN_DOC).adoc $(MAIN_DOC_INC) $(MAIN_DOC_IMG) | $(MAIN_DOC_BUILD_DIR)
+	asciidoctor --verbose --trace -a data-uri -a docprodtime="$(DATE_DOCPROD)" ${FINAL_TAG} $(MAIN_DOC).adoc -D $(MAIN_DOC_BUILD_DIR)
+	sed -E -i 's+(See&#160;)(https://cfconventions.org)(&#160;for&#160;further&#160;information.)+\1<a href="\2" target="_blank">\2</a>\3+' $(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).html
+
+$(MAIN_DOC_BUILD_DIR)/$(MAIN_DOC).pdf: $(MAIN_DOC).adoc $(MAIN_DOC_INC) $(MAIN_DOC_IMG) | $(MAIN_DOC_BUILD_DIR)
+	asciidoctor-pdf --verbose --trace -a docprodtime="$(DATE_DOCPROD)" ${FINAL_TAG} -d book -a pdf-theme=default-theme-CF-version.yml $(MAIN_DOC).adoc -D $(MAIN_DOC_BUILD_DIR)
+
+$(CONF_DOC_BUILD_DIR)/$(CONF_DOC).html: $(CONF_DOC_INC) | $(CONF_DOC_BUILD_DIR)
+	asciidoctor --verbose --trace ${FINAL_TAG} $(CONF_DOC).adoc -D $(CONF_DOC_BUILD_DIR)
+
+$(CONF_DOC_BUILD_DIR)/$(CONF_DOC).pdf: $(CONF_DOC_INC) | $(CONF_DOC_BUILD_DIR)
+	asciidoctor-pdf --verbose --trace ${FINAL_TAG} -d book $(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)
+	rm -rvf $(CONF_DOC_BUILD_DIR)
+
+#Rules to build non-static images. See MAIN_DOC_IMG_BLD above
+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 $@)

README.md

@@ -16,10 +16,33 @@ Their implementation in GitHub is described in this repository's [CONTRIBUTING.m
 
 To convert the AsciiDoc files into the resulting HTML file:
 
-1. Ensure you have [Ruby](https://www.ruby-lang.org/) installed (e.g. `sudo apt-get install ruby`)
-2. Ensure you have a recent version of [Asciidoctor](https://asciidoctor.org/) installed (e.g. `gem install asciidoctor`)
-3. Get hold of the AsciiDoc files in this repo (e.g. `git clone [email protected]:cf-metadata/cf-conventions.git`)
-4. Build the HTML: `asciidoctor cf-conventions.adoc`
+1. Ensure you have [Ruby](https://www.ruby-lang.org/) installed (e.g. `sudo apt install ruby`)
+1. Ensure you have a recent version of [Asciidoctor](https://asciidoctor.org/) installed (e.g. `gem install asciidoctor`)
+1. Ensure you have [Make](https://www.gnu.org/software/make/) installed (e.g. `sudo apt install make`)
+1. Get hold of the AsciiDoc files in this repo (e.g. `git clone [email protected]:cf-convention/cf-conventions.git`)
+1. Therare different options to make the conventions and conformance documents:
+   - (All, the default) HTML and PDF conventions and conformance documents: 
+      `make` or `make all`
+   - HTML conventions and conformance documents: 
+      `make html`
+   - PDF conventions and conformance documents: 
+      `make pdf`
+   - Conventions documents (HTML and PDF): 
+      `make conventions`
+   - Conformance documents (HTML and PDF): 
+      `make conformance`
+   - Delete documents and build directories:
+      `make clean`
+   - Build with FINAL tag and date stamp (remember to update version in `version.adoc` file ):
+      `make CF_FINAL=True`
+
+Both HTML documents are build with images embeded into the `.html` file.
+
+The build documents will be rendered into local paths:
+  - `conventions_build/cf-conventions.html`
+  - `conventions_build/cf-conventions.pdf`
+  - `conformance_build/conformance.html`
+  - `conformance_build/conformance.pdf`
 
 See the [GitHub help](https://help.github.com/) pages and plethora of other git/GitHub guides for more details on how to work with repos, forks, pull requests, etc.
 

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. "]
 |===============