Integrate gradle toolkit workspace

.github/workflows/preview.yml

@@ -14,10 +14,12 @@ defaults:
 env:
   doc_name: Transforms
 
-on:
+on:  # trigger on commit of files in the doc subdirectory
   push:
     branches:
-      - master
+    - master
+    paths:
+    - 'doc/**'
 
 jobs:
   build:

.gitignore

@@ -2,14 +2,28 @@
 # Project specific excludes
 #
 #
-# Binaries
+# ivoatex intermediate files
+*.aux
+*.bbl
+*.blg
+*.fdb_latexmk
+*.fls
+*.lof
+*.log
+*.out
+*.pdf
+*.toc
+ivoatexmeta.tex
 
 # vo-dml products
 *.cmap
 *.svrlt
 *.gvd
 *.validation-report.txt
 
+# vo-dml toolkit files
+.gradle
+
 # OS
 .DS_Store
 

work/README.md

@@ -0,0 +1,89 @@
+
+# Overview
+
+This is a workspace area for the development of the data model and subsequent generation
+of the various products derived from the vo-dml/XML representation of the model.
+
+Since there are many paths for generating the data model documents, the products themselves
+are stored in the other directories of this repository, and no software is installed in this
+workspace.  Instead, we provide the instructions for duplicating the workflow used to create
+the current products.
+
+# Data Modeling Tool
+
+The modeling itself is currently done using Modelio.  This includes the UML diagrams, and documentation
+of the model elements.  This is exported as an XMI (UML-2.4.1 format) document which can be found in the 'model'
+sibling directory.  The XMI file is processed using the VO-DML Toolkit to generate the VO-DML/XML file and
+other products.
+
+# VO-DML Toolkit plugin
+
+This toolkit provides a set of tasks for generating and translating vo-dml/XML files.
+For details on the toolkit, please see the "[Using the VO-DML Gradle Plugin](https://github.com/ivoa/vo-dml/tree/master/tools)"
+page of the [VO-DML repository](https://github.com/ivoa/vo-dml).
+
+The files included here are those necessary to execute the tasks outlined below.
+
+## Setup
+
+* Clone this repository
+  The toolkit is a command-line system
+
+* "[VO-DML Tools Guide](https://ivoa.github.io/vo-dml/)"
+  Guide on the VO-DML Toolkit and how to use it.
+
+* Install gradle
+  Instructions can be found on the "[Using the VO-DML Gradle Plugin](https://github.com/ivoa/vo-dml/tree/master/tools)" page.
+  There is no need to run the `gradle init` command, this space includes the files generated by that process tailored to
+  this particular model and directory structure.
+
+  Note: While gradle requires Java 8 or higher, the toolkit itself requires Java 11 in your environment.
+
+    * build.gradle.kts
+        * gradle connection to vo-dml toolkit plugin
+	* dependencies and required information (directory specs)
+	* register additional tasks
+    * settings.gradle.kts
+        * gradle support
+    * bindings_<model>_model.xml
+        * mapping between model and generated files.
+
+
+## Running Tasks
+
+The toolkit contains several tasks which can be used to generate and validate VO-DML/XML files, or translate them into
+various other formats or to code.  These instructions are focused on the tasks used to create and validate the
+VO-DML/XML files and generation of the standard HTML documentation.
+
+* ```%> gradle UMLToVODML```
+  This model is currently developed using the Modelio UML tool and exported to UML-2.4.1 format.
+  This command translates the XMI file into the VO-DML/XML representation.
+
+    * input, output, and translation script are specified with the task registration in build.gradle.kts
+    * the task locates the xmi file, and executes the specified translation script
+    * output is written to ./src/main/vo-dml/
+
+* ```%> gradle vodmlValidate```
+  Runs the VO-DML validation utility on the vo-dml/xml file.
+
+    * locates the vo-dml/XML file using the information contained in build.gradle.kts
+    * executes the validation utility
+    * output is echoed to the screen
+
+* ```%> gradle vodslToVodml --dml=<file spec for vo-dml/xml file> --dsl=<file spec to vodsl file>```
+  Runs a utility to VO-DML/XML files from models described in vodsl format.
+
+    * locates the vodsl file using the information contained in build.gradle.kts
+    * executes the translation task
+    * output is written to ./src/main/vodsl/
+
+* ```%> gradle vodmlDoc```
+  Runs a utility to generate HTML (and Tex) representation of the model.
+  Note:  This model does not use the Tex format output from this utility for the actual PDF document.
+
+    * locates the vo-dml/XML file using the information contained in build.gradle.kts
+    * executes the translation task
+    * output is written to ./build/generated/docs/vodml
+
+
+* Schema Generation

work/binding_transform_model.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<m:mappedModels xmlns:m="http://www.ivoa.net/xml/vodml-binding/v0.9.1">
+<!-- ========================================
+ -->
+<model>
+<name>trans</name>
+<file>Trans-v1.0.vo-dml.xml</file>
+    <java-package>org.ivoa.trans.transform</java-package>
+<xml-targetnamespace prefix="trans">http://ivoa.net/dm/models/vo-dml/xsd/trans/</xml-targetnamespace>
+</model>
+</m:mappedModels>

work/build.gradle.kts

@@ -0,0 +1,60 @@
+
+plugins {
+    // id("net.ivoa.vo-dml.vodmltools") version "0.4.5"    << requires gradle version 8.0+
+    id("net.ivoa.vo-dml.vodmltools") version "0.3.14"
+}
+
+group = "org.javastro.ivoa.dm"     // "net.ivoa.vo-dml"
+version = "0.4.1-SNAPSHOT"         // "0.2-SNAPSHOT"
+
+// Settings for all vodml tools
+vodml {
+     // where to find the vodml XML files (using 'project' structure)
+     //  - defaults to src/main/vo-dml
+     //vodmlDir.set( file("<path to vo-dml files>") )
+
+     // identify the vodml XML files 
+     //   - defaults to all "*.vo-dml.xml" files in vodmlDir
+     //vodmlFiles.setFrom( project.files( vodmlDir.file("Trans-v1.0.vo-dml.xml") ))
+
+     // where to find the VODSL files
+     //  - defaults to src/main/vodsl
+     //vodslDir.set( file("./src/main/vodsl") )
+
+     // identify the VODSL files (using 'project' structure)
+     //   - defaults to all "*.vodsl" files in vodslDir
+     //vodslFiles.setFrom( project.files( vodslDir.file("Trans-v1.0.vodsl") ))
+
+     // where to find the binding file(s)
+     //   - finds them by pattern in the project file tree. (eg: binding_proposal_model.xml )
+     bindingFiles.setFrom( project.files(
+                             layout.projectDirectory.asFileTree.matching( PatternSet().include("binding*model.xml") )
+                           ))
+
+     // where to put output from vodmlDoc task
+     outputDocDir.set(layout.projectDirectory.dir("std/generated"))
+
+     // where to put output from vodmlSite task ( toolkit 0.4.5 )
+     // outputSiteDir.set(layout.projectDirectory.dir("docs/generated"))
+
+     // which models to process ( for repos containing multiple models? )
+     modelsToDocument.set("transform")
+}
+
+// Register task to execute UML converter which is very custom
+tasks.register( "UmlToVodml", net.ivoa.vodml.gradle.plugin.XmiTask::class.java){
+    // ----------------------------------------------------------
+    // creates build/tmp/UmlToVodml tree to write temporary files
+    // ----------------------------------------------------------
+    description = "convert UML to VO-DML"
+
+    // the conversion script to use
+    xmiScript.set("xmi2vo-dml_Modelio3.7_UML2.4.1.xsl")
+
+    // where to find the UML XMI file
+    xmiFile.set(file("../model/trans_1.0_uml2p4p1.xmi"))
+
+    // output VO-DML/XML file to 'project' tree structure
+    //  - this lets us use a lot of default settings in the vodml block
+    vodmlFile.set(file("./src/main/vo-dml/Trans-v1.0.vo-dml.xml"))
+}

work/settings.gradle.kts

@@ -0,0 +1,27 @@
+rootProject.name = "TransformDM"
+
+// space for gradle toolkit to work within
+//   - this doesn't appear to be necessary
+include("work")
+
+
+pluginManagement {
+    repositories {
+        mavenLocal() // IMPL allow picking up from local - should be removed when publishing
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositories {
+        mavenLocal()
+        mavenCentral()
+        /*
+        add this repository to pick up the SNAPSHOT version of the IVOA base library - in the future when this
+        will not be necessary when this library is released as a non-SNAPSHOT version.
+         */
+        maven {
+            url= uri("https://oss.sonatype.org/content/repositories/snapshots/")
+        }
+    }
+}