Merge pull request #46 from wendellpiez/issue42-docs-gen-scripting

new XProc for docs generation; cleanup and renaming
usnistgov · Aug 10, 2023 · 68a21bc · 68a21bc
2 parents 534cde1 + 25a9fa5
commit 68a21bc
Show file tree

Hide file tree

Showing 11 changed files with 302 additions and 810 deletions.
diff --git a/bin/metaschema-xslt b/bin/metaschema-xslt
@@ -15,6 +15,8 @@ usage() {
 Usage: $(basename "${BASH_SOURCE[0]}") [ARGS] SUBCOMMAND [SUBCOMMAND ARGS]
 
 Subcommands:
+- docs-testsite METASCHEMA_XML OUTPUT_DIR SCHEMA_NAME [ADDITIONAL_ARGS]
+    Generate a set of standalone (self-contained) HTML pages with XML and JSON Schema documentation for a given metaschema, for testing
 - schema-gen METASCHEMA_XML OUTPUT_DIR SCHEMA_NAME [ADDITIONAL_ARGS]
     Generate JSON and XML schemas for a given metaschema
 - converter-gen METASCHEMA_XML OUTPUT_DIR SCHEMA_NAME [ADDITIONAL_ARGS]
@@ -51,6 +53,9 @@ BASE_COMMAND="$(basename "${BASH_SOURCE[0]}") $SUBCOMMAND"
 export BASE_COMMAND
 
 case "$SUBCOMMAND" in
+    docs-testsite)
+        "$SRC_DIR"/document/mvn-schemadocs-testsite-xpl.sh "$@"
+        ;;
     schema-gen)
         "$SRC_DIR"/schema-gen/mvn-schemas-xpl.sh "$@"
         ;;

diff --git a/src/document/METASCHEMA-DOCS-DIVS-write.xpl b/src/document/METASCHEMA-DOCS-DIVS-write.xpl
@@ -0,0 +1,114 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:c="http://www.w3.org/ns/xproc-step"
+  version="1.0" xmlns:metaschema="http://csrc.nist.gov/ns/metaschema/1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" type="metaschema:METASCHEMA-DOCS-DIVS-write"
+  name="METASCHEMA-DOCS-DIVS-write">
+
+  <!-- Purpose: Emit XML and JSON-oriented metaschema documentation FILE FRAGMENTS (`div` elements) -->
+  <!-- Input: A valid and correct OSCAL Metaschema instance linked to its modules (also valid and correct) -->
+  <!-- Input: options 'path' and 'metaschema-id' must be set, to populate a/@href in crosslinks -->
+  <!-- Output: Writes outputs to designated subdirectory; exposes no ports -->
+
+  <!-- NIST/ITL Metaschema github.com/usnistgov/metaschema https://pages.nist.gov/metaschema/ -->
+
+  <!-- &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& -->
+  <!-- Ports -->
+
+  <p:input port="METASCHEMA" primary="true"/>
+
+  <p:input port="parameters" kind="parameter"/>
+
+  <!--<p:option name="metaschema-id" select="'oscal'"/>-->
+
+  <p:option name="output-path" required="true"/>
+  <p:option name="metaschema-id" required="true"/>
+
+  <p:option name="json-outline-filename"     select="$metaschema-id || '-json-outline.html'"/>
+  <p:option name="json-reference-filename"   select="$metaschema-id || '-json-reference.html'"/>
+  <p:option name="json-index-filename"       select="$metaschema-id || '-json-index.html'"/>
+  <p:option name="json-definitions-filename" select="$metaschema-id || '-json-definitions.html'"/>
+  <p:option name="xml-outline-filename"      select="$metaschema-id || '-xml-outline.html'"/>
+  <p:option name="xml-reference-filename"    select="$metaschema-id || '-xml-reference.html'"/>
+  <p:option name="xml-index-filename"        select="$metaschema-id || '-xml-index.html'"/>
+  <p:option name="xml-definitions-filename"  select="$metaschema-id || '-xml-definitions.html'"/>
+
+  <!-- &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& -->
+  <!-- Import (subpipeline) -->
+
+  <p:import href="METASCHEMA-DOCS-TRACE.xpl"/>
+
+  <p:variable name="xml-outline-uri"      select="resolve-uri($xml-outline-filename,     $output-path)"/>
+  <p:variable name="xml-reference-uri"    select="resolve-uri($xml-reference-filename,   $output-path)"/>
+  <p:variable name="xml-index-uri"        select="resolve-uri($xml-index-filename,       $output-path)"/>
+  <p:variable name="xml-definitions-uri"  select="resolve-uri($xml-definitions-filename, $output-path)"/>
+  <p:variable name="json-outline-uri"     select="resolve-uri($json-outline-filename,    $output-path)"/>
+  <p:variable name="json-reference-uri"   select="resolve-uri($json-reference-filename,  $output-path)"/>
+  <p:variable name="json-index-uri"       select="resolve-uri($json-index-filename,      $output-path)"/>
+  <p:variable name="json-definitions-uri" select="resolve-uri($json-definitions-filename,$output-path)"/>
+
+  <!--  * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * -->
+
+  <!-- Implicit source is on the METASCHEMA input port -->
+
+  <metaschema:metaschema-docs-trace name="DOCS-PIPELINE">
+    <!--<p:with-option name="output-path"   select="$output-path"/>-->
+    <p:with-option name="metaschema-id" select="$metaschema-id"/>
+  </metaschema:metaschema-docs-trace>
+
+  <p:store  method="html" version="5.0">
+    <p:with-option name="href" select="$json-outline-uri"/>
+    <p:input port="source">
+      <p:pipe step="DOCS-PIPELINE" port="JSON-object-map-div"/>
+    </p:input>
+  </p:store>
+
+  <p:store method="html" version="5.0">
+    <p:with-option name="href" select="$json-reference-uri"/>
+    <p:input port="source">
+      <p:pipe step="DOCS-PIPELINE" port="JSON-object-reference-div"/>
+    </p:input>
+  </p:store>
+
+  <p:store method="html" version="5.0">
+    <p:with-option name="href" select="$json-index-uri"/>
+    <p:input port="source">
+      <p:pipe step="DOCS-PIPELINE" port="JSON-object-index-div"/>
+    </p:input>
+  </p:store>
+
+  <p:store method="html" version="5.0">
+    <p:with-option name="href" select="$json-definitions-uri"/>
+    <p:input port="source">
+      <p:pipe step="DOCS-PIPELINE" port="JSON-definitions-div"/>
+    </p:input>
+  </p:store>
+
+  <p:store method="html" version="5.0">
+    <p:with-option name="href" select="$xml-outline-uri"/>
+    <p:input port="source">
+      <p:pipe step="DOCS-PIPELINE" port="XML-element-map-div"/>
+    </p:input>
+  </p:store>
+
+  <p:store method="html" version="5.0">
+    <p:with-option name="href" select="$xml-reference-uri"/>
+    <p:input port="source">
+      <p:pipe step="DOCS-PIPELINE" port="XML-element-reference-div"/>
+    </p:input>
+  </p:store>
+
+  <p:store method="html" version="5.0">
+    <p:with-option name="href" select="$xml-index-uri"/>
+    <p:input port="source">
+      <p:pipe step="DOCS-PIPELINE" port="XML-element-index-div"/>
+    </p:input>
+  </p:store>
+
+  <p:store method="html" version="5.0">
+    <p:with-option name="href" select="$xml-definitions-uri"/>
+    <p:input port="source">
+      <p:pipe step="DOCS-PIPELINE" port="XML-definitions-div"/>
+    </p:input>
+  </p:store> 
+
+</p:declare-step>
diff --git a/src/document/METASCHEMA-DOCS-DIVS.xpl b/src/document/METASCHEMA-DOCS-DIVS.xpl
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:c="http://www.w3.org/ns/xproc-step"
+  version="1.0" xmlns:metaschema="http://csrc.nist.gov/ns/metaschema/1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" type="metaschema:METASCHEMA-DOCS-DIVS"
+  name="METASCHEMA-DOCS-DIVS">
+
+  <!-- Purpose: Emit XML and JSON-oriented metaschema documentation FILE FRAGMENTS (`div` elements) -->
+  <!-- Input: A valid and correct OSCAL Metaschema instance linked to its modules (also valid and correct) -->
+  <!-- Input: options 'path' and 'metaschema-id' must be set, to populate a/@href in crosslinks -->
+  <!-- Output: exposes outputs on named ports -->
+
+  <!-- NIST/ITL Metaschema github.com/usnistgov/metaschema https://pages.nist.gov/metaschema/ -->
+
+  <!-- &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& -->
+  <!-- Ports -->
+
+  <p:input port="METASCHEMA" primary="true"/>
+
+  <p:input port="parameters" kind="parameter"/>
+
+  <!--<p:option name="metaschema-id" select="'oscal'"/>-->
+
+  <!--<p:option name="output-path" required="true"/>-->
+  <p:option name="metaschema-id" required="true"/>
+
+  <!--<p:option name="json-outline-filename"     select="$metaschema-id || '-json-outline.html'"/>
+  <p:option name="json-reference-filename"   select="$metaschema-id || '-json-reference.html'"/>
+  <p:option name="json-index-filename"       select="$metaschema-id || '-json-index.html'"/>
+  <p:option name="json-definitions-filename" select="$metaschema-id || '-json-definitions.html'"/>
+  <p:option name="xml-outline-filename"      select="$metaschema-id || '-xml-outline.html'"/>
+  <p:option name="xml-reference-filename"    select="$metaschema-id || '-xml-reference.html'"/>
+  <p:option name="xml-index-filename"        select="$metaschema-id || '-xml-index.html'"/>
+  <p:option name="xml-definitions-filename"  select="$metaschema-id || '-xml-definitions.html'"/>-->
+
+  <p:serialization port="JSON-object-map-div" indent="true" method="html" version="5.0"/>
+  <p:output        port="JSON-object-map-div" primary="false">
+    <p:pipe step="DOCS-PIPELINE" port="JSON-object-index-div"/>
+  </p:output>
+
+  <p:serialization port="JSON-object-reference-div" indent="true" method="html" version="5.0"/>
+  <p:output        port="JSON-object-reference-div" primary="false">
+    <p:pipe step="DOCS-PIPELINE" port="JSON-object-reference-div"/>
+  </p:output>
+
+  <p:serialization port="JSON-object-index-div" indent="true" method="html" version="5.0"/>
+  <p:output        port="JSON-object-index-div" primary="false">
+    <p:pipe step="DOCS-PIPELINE" port="JSON-object-map-div"/>
+  </p:output>
+
+  <p:serialization port="JSON-definitions-div" indent="true" method="html" version="5.0"/>
+  <p:output        port="JSON-definitions-div" primary="false">
+    <p:pipe step="DOCS-PIPELINE" port="JSON-definitions-div"/>
+  </p:output>
+
+  <p:serialization port="XML-element-map-div" indent="true" method="html" version="5.0"/>
+  <p:output        port="XML-element-map-div" primary="false">
+    <p:pipe step="DOCS-PIPELINE" port="XML-element-index-div"/>
+  </p:output>
+
+  <p:serialization port="XML-element-reference-div" indent="true" method="html" version="5.0"/>
+  <p:output        port="XML-element-reference-div" primary="false">
+    <p:pipe step="DOCS-PIPELINE" port="XML-element-reference-div"/>
+  </p:output>
+
+  <p:serialization port="XML-element-index-div" indent="true" method="html" version="5.0"/>
+  <p:output        port="XML-element-index-div" primary="false">
+    <p:pipe step="DOCS-PIPELINE" port="XML-element-map-div"/>
+  </p:output>
+
+  <p:serialization port="XML-definitions-div" indent="true" method="html" version="5.0"/>
+  <p:output        port="XML-definitions-div" primary="false">
+    <p:pipe step="DOCS-PIPELINE" port="XML-definitions-div"/>
+  </p:output>
+
+  <!-- &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& &&& -->
+  <!-- Import (subpipeline) -->
+
+  <p:import href="METASCHEMA-DOCS-TRACE.xpl"/>
+
+  <!--  * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * . * -->
+
+  <!-- Implicit source is on the METASCHEMA input port -->
+
+  <metaschema:metaschema-docs-trace name="DOCS-PIPELINE">
+    <!--<p:with-option name="output-path"   select="$output-path"/>-->
+    <p:with-option name="metaschema-id" select="$metaschema-id"/>
+  </metaschema:metaschema-docs-trace>
+
+</p:declare-step>
diff --git a/src/document/METASCHEMA-HTML-DOCS.xpl → ...cument/METASCHEMA-DOCS-TESTSITE-write.xpl b/src/document/METASCHEMA-HTML-DOCS.xpl → ...cument/METASCHEMA-DOCS-TESTSITE-write.xpl
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:c="http://www.w3.org/ns/xproc-step"
   version="1.0" xmlns:metaschema="http://csrc.nist.gov/ns/metaschema/1.0"
-  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" type="metaschema:METASCHEMA-HTML-DOCS"
-  name="METASCHEMA-HTML-DOCS">
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" type="metaschema:METASCHEMA-DOCS-TESTSITE-write"
+  name="METASCHEMA-DOCS-TESTSITE-write">
 
   <!-- Purpose: Emit XML and JSON-oriented metaschema documentation -->
   <!-- Input: A valid and correct OSCAL Metaschema instance linked to its modules (also valid and correct) -->

diff --git a/src/document/METASCHEMA-DOCS-TRACE.xpl b/src/document/METASCHEMA-DOCS-TRACE.xpl
@@ -63,46 +63,86 @@
     <p:pipe        port="result"               step="make-json-object-tree"/>
   </p:output>
 
+  <p:serialization port="JSON-object-map-div" indent="true"/>
+  <p:output        port="JSON-object-map-div" primary="false">
+    <p:pipe        port="result"               step="make-json-model-map"/>
+  </p:output>
+
   <p:serialization port="JSON-object-map-html" indent="true"/>
   <p:output        port="JSON-object-map-html" primary="false">
     <p:pipe        port="result"               step="style-json-model-map"/>
   </p:output>
 
+  <p:serialization port="JSON-object-reference-div" indent="true"/>
+  <p:output        port="JSON-object-reference-div" primary="false">
+    <p:pipe        port="result"                     step="render-json-object-reference"/>
+  </p:output>
+
   <p:serialization port="JSON-object-reference-html" indent="true"/>
   <p:output        port="JSON-object-reference-html" primary="false">
     <p:pipe        port="result"                     step="style-json-object-reference"/>
   </p:output>
 
+  <p:serialization port="JSON-object-index-div" indent="true"/>
+  <p:output        port="JSON-object-index-div" primary="false">
+    <p:pipe        port="result"                 step="render-json-object-index"/>
+  </p:output>
+
   <p:serialization port="JSON-object-index-html" indent="true"/>
   <p:output        port="JSON-object-index-html" primary="false">
     <p:pipe        port="result"                 step="style-json-object-index"/>
   </p:output>
 
+  <p:serialization port="JSON-definitions-div" indent="true"/>
+  <p:output        port="JSON-definitions-div" primary="false">
+    <p:pipe        port="result"                step="render-json-definitions"/>
+  </p:output>
+
   <p:serialization port="JSON-definitions-html" indent="true"/>
   <p:output        port="JSON-definitions-html" primary="false">
     <p:pipe        port="result"                step="style-json-definitions"/>
   </p:output>
-
+  
   <p:serialization port="XML-element-tree-xml" indent="true"/>
   <p:output        port="XML-element-tree-xml" primary="false">
     <p:pipe        port="result"               step="make-xml-element-tree"/>
   </p:output>
 
+  <p:serialization port="XML-element-map-div" indent="true"/>
+  <p:output        port="XML-element-map-div" primary="false">
+    <p:pipe        port="result"               step="make-xml-model-map"/>
+  </p:output>
+
   <p:serialization port="XML-element-map-html" indent="true"/>
   <p:output        port="XML-element-map-html" primary="false">
     <p:pipe        port="result"               step="style-xml-model-map"/>
   </p:output>
 
+  <p:serialization port="XML-element-reference-div" indent="true"/>
+  <p:output        port="XML-element-reference-div" primary="false">
+    <p:pipe        port="result"               step="render-xml-element-reference"/>
+  </p:output>
+
   <p:serialization port="XML-element-reference-html" indent="true"/>
   <p:output        port="XML-element-reference-html" primary="false">
     <p:pipe        port="result"               step="style-xml-element-reference"/>
   </p:output>
 
+  <p:serialization port="XML-element-index-div" indent="true"/>
+  <p:output        port="XML-element-index-div" primary="false">
+    <p:pipe        port="result"                 step="render-xml-element-index"/>
+  </p:output>
+
   <p:serialization port="XML-element-index-html" indent="true"/>
   <p:output        port="XML-element-index-html" primary="false">
     <p:pipe        port="result"                 step="style-xml-element-index"/>
   </p:output>
 
+  <p:serialization port="XML-definitions-div" indent="true"/>
+  <p:output        port="XML-definitions-div" primary="false">
+    <p:pipe        port="result"                step="render-xml-definitions"/>
+  </p:output>
+
   <p:serialization port="XML-definitions-html" indent="true"/>
   <p:output        port="XML-definitions-html" primary="false">
     <p:pipe        port="result"                step="style-xml-definitions"/>

diff --git a/src/document/Makefile b/src/document/Makefile
@@ -8,22 +8,20 @@ output_folder:=$(abspath test_output)
 test: smoke-test ## Run all tests
 
 .PHONY: smoke-test
-smoke-test: smoke-test-hugo smoke-test-standalone ## Run all smoke-tests
+smoke-test: smoke-test-hugo smoke-test-testsite ## Run all smoke-tests
 
 .PHONY: smoke-test-hugo
-smoke-test-hugo: ## Test verifies that 'write-hugo-metaschema-docs.xpl' runs without error
-	$(call EXEC_CALABASH,-i source=$(test_metaschema) output-path=file://$(output_folder)/smoke/hugo/ write-hugo-metaschema-docs.xpl)
+smoke-test-hugo: ## Test verifies that 'METASCHEMA-DOCS-DIVS-write.xpl' runs without error
+	$(call EXEC_CALABASH,-iMETASCHEMA=$(test_metaschema) METASCHEMA-DOCS-DIVS-write.xpl output-path=file://$(output_folder)/smoke/hugo/ metaschema-id=models_metaschema)
 
-.PHONY: smoke-test-standalone
-smoke-test-standalone: ## Test verifies that make-metaschema-standalone-docs.xpl runs without error
-	$(call EXEC_CALABASH,-i source=$(test_metaschema) \
-		output-path=file://$(output_folder)/smoke/standalone/ \
-		-o INT_0_echo-input=/dev/null \
-		-o INT_1_composed=/dev/null \
-		-o INT_2_abstract-model-map=/dev/null \
-		-o INT_3_unfolded-instance-map=/dev/null \
-		-o INT_4_marked-instance-map=/dev/null \
-		make-metaschema-standalone-docs.xpl)
+.PHONY: smoke-test-testsite
+smoke-test-testsite: ## Test verifies that METASCHEMA-DOCS-TESTSITE-write.xpl runs without error
+	./mvn-schemadocs-testsite-xpl.sh "$(test_metaschema)" test_output/smoke/testsite models_metaschema
+
+#	$(call EXEC_CALABASH,-iMETASCHEMA=$(test_metaschema) \
+#		METASCHEMA-DOCS-TESTSITE-write.xpl \
+#		output-path=file://$(output_folder)/smoke/testsite/ \
+#		metaschema-id=models_metaschema)
 
 clean: ## Remove test output
-	rm -fr $(smoke-test_output)
+	rm -fr $(output_folder)