From 3e5ad6486c05cd73c6a201498c5ec42f6c047b78 Mon Sep 17 00:00:00 2001
From: olabusayoT <50379531+olabusayoT@users.noreply.github.com>
Date: Mon, 14 Oct 2024 12:10:00 -0400
Subject: [PATCH] Add SBT task to generate tunables doc

- currently we hardcode the description of tunables on daffodil-site. This list is out of date. Instead, the fix uses an sbt task 'genTunablesDoc' to generate a markdown document from the dafext.xsd and outputs it to target/tunables.md

DAFFODIL-2758
---
 build.sbt | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 102 insertions(+), 1 deletion(-)

diff --git a/build.sbt b/build.sbt
index a711217bfa..58ac01f026 100644
--- a/build.sbt
+++ b/build.sbt
@@ -24,6 +24,7 @@ lazy val genProps = taskKey[Seq[File]]("Generate properties scala source")
 lazy val genSchemas = taskKey[Seq[File]]("Generate DFDL schemas")
 lazy val genCExamples = taskKey[Seq[File]]("Generate C example files")
 lazy val genVersion = taskKey[Seq[File]]("Generate VERSION file")
+lazy val genTunablesDoc = taskKey[Unit]("Generate tunables docs from dafext.xsd file")
 
 lazy val daffodil = project
   .in(file("."))
@@ -52,7 +53,14 @@ lazy val daffodil = project
     tutorials,
     udf
   )
-  .settings(commonSettings, nopublish, ratSettings, unidocSettings, genCExamplesSettings)
+  .settings(
+    commonSettings,
+    nopublish,
+    ratSettings,
+    unidocSettings,
+    genTunablesDocSettings,
+    genCExamplesSettings
+  )
 
 lazy val macroLib = Project("daffodil-macro-lib", file("daffodil-macro-lib"))
   .settings(commonSettings, nopublish)
@@ -481,6 +489,99 @@ lazy val unidocSettings =
       (JavaUnidoc / unidoc / unidocAllSources).value.map(apiDocSourceFilter)
   )
 
+lazy val genTunablesDocSettings = Seq(
+  Compile / genTunablesDoc := {
+    val dafExtFile =
+      (propgen / Compile / resources).value.filter(_.getName == "dafext.xsd").head
+    val outputDocFile = (Compile / target).value / "tunables.md"
+    // parse xsd file
+    val dafExtXml = scala.xml.XML.loadFile(dafExtFile)
+    // extract information
+    val tunablesSeq = (dafExtXml \ "element" \\ "element")
+    // build documentation
+    val sectionsSeq = tunablesSeq.flatMap { ele =>
+      val subtitle = ele \@ "name"
+      val documentation = (ele \ "annotation" \ "documentation").text
+      val sections =
+        if (documentation.nonEmpty && !documentation.trim.startsWith("Deprecated")) {
+          val s =
+            s"""
+            |#### $subtitle
+            |$documentation
+            |""".stripMargin
+          Some(s)
+        } else {
+          None
+        }
+      sections
+    }
+    val documentationPage =
+      s"""|---
+        |layout: page
+        |title: DFDL Tunables
+        |group: nav-right
+        |---
+        |<!--
+        |{% comment %}
+        |Licensed to the Apache Software Foundation (ASF) under one or more
+        |contributor license agreements.  See the NOTICE file distributed with
+        |this work for additional information regarding copyright ownership.
+        |The ASF licenses this file to you under the Apache License, Version 2.0
+        |(the "License"); you may not use this file except in compliance with
+        |the License.  You may obtain a copy of the License at
+        |
+        |http://www.apache.org/licenses/LICENSE-2.0
+        |
+        |Unless required by applicable law or agreed to in writing, software
+        |distributed under the License is distributed on an "AS IS" BASIS,
+        |WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        |See the License for the specific language governing permissions and
+        |limitations under the License.
+        |{% endcomment %}
+        |-->
+        |<!--
+        |{% comment %}
+        |This file is generated using ``sbt genTunablesDoc``. Update that task in Daffodil to update this file.
+        |{% endcomment %}
+        |-->
+        |
+        |Daffodil provides tunables as a way to change its behavior.
+        |Tunables are set by way of the ``tunables`` element in [config files](/configuration)
+        |or from the [cli](/cli) via the ``-T`` option.
+        |
+        |#### Config Example
+        | ``` xml
+        | <daf:dfdlConfig
+        |	xmlns:daf="urn:ogf:dfdl:2013:imp:daffodil.apache.org:2018:ext">
+        |    <daf:tunables>
+        |      <daf:suppressSchemaDefinitionWarnings>
+        |        encodingErrorPolicyError
+        |      </daf:suppressSchemaDefinitionWarnings>
+        |    </daf:tunables>
+        |</daf:dfdlConfig>
+        | ```
+        |
+        | The config file can then be passed into daffodil subcommands via the ``-c|--config`` options.
+        |
+        |#### CLI Example
+        | ``` bash
+        | daffodil parse -s schema.xsd -TsuppressSchemaDefinitionWarnings="encodingErrorPolicyError" data.bin
+        | ```
+        |
+        |
+        |### Definitions
+        |${sectionsSeq.mkString("\n")}
+        |""".stripMargin
+    IO.write(outputDocFile, s"$documentationPage")
+    println(s"Generated tunables documentation at: $outputDocFile")
+  },
+  Compile / compile := {
+    val res = (Compile / compile).value
+    (Compile / genTunablesDoc).value
+    res
+  }
+)
+
 lazy val genCExamplesSettings = Seq(
   Compile / genCExamples := {
     val cp = (codeGenC / Test / dependencyClasspath).value