Added --documentNumber option to icd-db and field to PDF options popu…

…p to specify optional document number to display under the subtitle in the generated PDF.

CHANGELOG.md

@@ -10,6 +10,8 @@ See also [JsonSchemaChanges.md](JsonSchemaChanges.md) for a list of changes in t
   database. Also added a check for cases found in already published APIs.
 - Minor performance improvements
 - Added details table for published images to generated PDFs and changed the format used for the web version
+- Added --documentNumber option to icd-db (and text field to web app's PDF options popup). If given, the text is
+  displayed under the subtitle in the generated PDF
 
 ## [ICD v2.2.0] - 2022-11-01
 

icd-db/README.md

@@ -43,7 +43,7 @@ Usage: icd-db [options]
   --component2 <name>      Specifies the subsytem2 component to be used by any following options (subsystem2 must also be specified)
   --icdversion <icd-version>
                            Specifies the version to be used by any following options (overrides subsystem and subsystem2 versions)
-  -o, --out <outputFile>   Saves the selected API (or ICD) to the given file in a format based on the file's suffix (html, pdf) or generates code for the given API in a language based on the suffix (scala, java, ts (typescript))
+  -o, --out <outputFile>   Saves the selected API (or ICD) to the given file in a format based on the file's suffix (html, pdf) or generates code for the given API in a language based on the suffix ('scala', 'java', 'ts' (typescript), py (python))
   --drop [db|subsystem|component]
                            Drops the specified component, subsystem, or the entire icd database (requires restart of icd web app)
   --versions <subsystem>   List the version history of the given subsystem
@@ -61,7 +61,8 @@ Usage: icd-db [options]
   --lineHeight <height>    For PDF or HTML file output: The line height (default: 1.6)
   --paperSize [Letter|Legal|A4|A3]
                            For PDF output: The paper size (default: Letter)
-  --package package.name   Package name for generated Scala or Java files (default: no package)
+  --documentNumber text    For PDF output: An optional document number to display after the title/subtitle
+  --package package.name   Package name for generated Scala files (default: no package)
   --help
   --version
 ```

icd-db/src/main/scala/csw/services/icd/PdfCache.scala

@@ -181,7 +181,7 @@ class PdfCache(cacheDir: File) {
           lineHeights.foreach { lh =>
             paperSizes.foreach { ps =>
               List(true, false).foreach { clientApi =>
-                val pdfOptions = PdfOptions(orient, fs, lh, ps, details = true, Nil, processMarkdown = false)
+                val pdfOptions = PdfOptions(orient, fs, lh, ps, details = true, Nil, processMarkdown = false, documentNumber = "")
                 val file       = getFile(sv, pdfOptions)
                 if (file.exists())
                   file.delete()
@@ -204,7 +204,7 @@ class PdfCache(cacheDir: File) {
         fontSizes.foreach { fs =>
           lineHeights.foreach { lh =>
             paperSizes.foreach { ps =>
-              val pdfOptions = PdfOptions(orient, fs, lh, ps, details = true, Nil, processMarkdown = false)
+              val pdfOptions = PdfOptions(orient, fs, lh, ps, details = true, Nil, processMarkdown = false, documentNumber = "")
               val file       = getFile(sv, targetSv, pdfOptions)
               if (file.exists())
                 file.delete()

icd-db/src/main/scala/csw/services/icd/db/IcdDb.scala

@@ -182,6 +182,10 @@ object IcdDb extends App {
       c.copy(paperSize = Some(x))
     } text "For PDF output: The paper size (default: Letter)"
 
+    opt[String]("documentNumber") valueName "text" action { (x, c) =>
+      c.copy(documentNumber = Some(x))
+    } text "For PDF output: An optional document number to display after the title/subtitle"
+
     opt[String]("package") valueName "package.name" action { (x, c) =>
       c.copy(packageName = Some(x))
     } text "Package name for generated Scala files (default: no package)"
@@ -229,7 +233,8 @@ object IcdDb extends App {
       options.lineHeight,
       options.paperSize,
       Some(true),
-      Nil
+      Nil,
+      documentNumber = options.documentNumber.getOrElse("")
     )
 
     options.ingest.map { dir =>

icd-db/src/main/scala/csw/services/icd/db/IcdDbOptions.scala

@@ -32,5 +32,6 @@ case class IcdDbOptions(
     fontSize: Option[Int] = None,
     lineHeight: Option[String] = None,
     paperSize: Option[String] = None,
+    documentNumber: Option[String] = None,
     packageName: Option[String] = None,
 )

icd-db/src/main/scala/csw/services/icd/db/IcdDbPrinter.scala

@@ -133,7 +133,7 @@ case class IcdDbPrinter(
     } yield {
       import scalatags.Text.all._
       val infoList               = getComponentInfo(versionManager, sv, Some(targetSv), fitsKeyMap)
-      val titleInfo              = TitleInfo(subsystemInfo, Some(targetSv), maybeIcdVersion)
+      val titleInfo              = TitleInfo(subsystemInfo, Some(targetSv), maybeIcdVersion, documentNumber = pdfOptions.documentNumber)
       val titleInfo1             = TitleInfo(subsystemInfo, Some(targetSv), maybeIcdVersion, "(Part 1)")
       val infoList2              = getComponentInfo(versionManager, targetSv, Some(sv), fitsKeyMap)
       val titleInfo2             = TitleInfo(targetSubsystemInfo, Some(sv), maybeIcdVersion, "(Part 2)")

icd-db/src/main/scala/csw/services/icd/html/IcdToHtml.scala

@@ -152,7 +152,7 @@ object IcdToHtml {
     import scalatags.Text.all._
 
     val nh           = new NumberedHeadings
-    val titleInfo    = TitleInfo(subsystemInfo, None, None)
+    val titleInfo    = TitleInfo(subsystemInfo, None, None, documentNumber = pdfOptions.documentNumber)
     val summaryTable = SummaryTable.displaySummary(subsystemInfo, None, infoList, nh, clientApi, displayTitle = true)
 
     val mainContent = div(
@@ -184,9 +184,25 @@ object IcdToHtml {
     import scalatags.Text.all._
     titleInfo.maybeSubtitle match {
       case Some(subtitle) =>
-        h3(a(name := titleId), cls := "page-header")(titleInfo.title, br, small(cls := "text-secondary")(subtitle))
+        titleInfo.maybeDocumentNumber match {
+          case Some(documentNumber) =>
+            h3(a(name := titleId), cls := "page-header")(
+              titleInfo.title,
+              br,
+              small(cls := "text-secondary")(subtitle),
+              br,
+              small(cls := "text-secondary")(documentNumber)
+            )
+          case None =>
+            h3(a(name := titleId), cls := "page-header")(titleInfo.title, br, small(cls := "text-secondary")(subtitle))
+        }
       case None =>
-        h3(a(name := titleId), cls := "page-header")(titleInfo.title)
+        titleInfo.maybeDocumentNumber match {
+          case Some(documentNumber) =>
+            h3(a(name := titleId), cls := "page-header")(titleInfo.title, br, small(cls := "text-secondary")(documentNumber))
+          case None =>
+            h3(a(name := titleId), cls := "page-header")(titleInfo.title)
+        }
     }
   }
 

icd-web-client/src/main/scala/icd/web/client/ClientRoutes.scala

@@ -45,7 +45,8 @@ object ClientRoutes {
         s"fontSize=${o.fontSize}",
         s"lineHeight=${o.lineHeight}",
         s"paperSize=${o.paperSize}",
-        s"details=${o.details}"
+        s"details=${o.details}",
+        s"documentNumber=${o.documentNumber}",
       ).mkString("&")
     )
     val graphAttrs = maybeGraphOptions.map(o =>

icd-web-client/src/main/scala/icd/web/client/IcdWebClient.scala

@@ -46,7 +46,7 @@ case class IcdWebClient(csrfToken: String, inputDirSupported: Boolean) {
   private val fitsDictionaryItem =
     NavbarItem("FITS Dictionary", "Display information about all FITS keywords", showFitsDictionary())
 
-  private val pdfItem = NavbarPdfItem("PDF", "Generate and display a PDF for the API or ICD", makePdf)
+  private val pdfItem = NavbarPdfItem("PDF", "Generate and display a PDF for the API or ICD", makePdf, showDocumentNumber = true)
   pdfItem.setEnabled(false)
 
   private val generateItem = NavbarDropDownItem(
@@ -64,7 +64,8 @@ case class IcdWebClient(csrfToken: String, inputDirSupported: Boolean) {
   private val archiveItem = NavbarPdfItem(
     "Archive",
     "Generate and display an 'Archived Items' report for the selected subsystem (or all subsystems)",
-    makeArchivedItemsReport
+    makeArchivedItemsReport,
+    showDocumentNumber = false
   )
 
   private val navbar = Navbar()
@@ -557,11 +558,12 @@ case class IcdWebClient(csrfToken: String, inputDirSupported: Boolean) {
     import icd.web.shared.JsonSupport._
     setSidebarVisible(false)
     val f = for {
-      fitsDict <- Fetch
-        .get(ClientRoutes.fitsDictionary(None))
-        .map { text =>
-          Json.fromJson[FitsDictionary](Json.parse(text)).get
-        }
+      fitsDict <-
+        Fetch
+          .get(ClientRoutes.fitsDictionary(None))
+          .map { text =>
+            Json.fromJson[FitsDictionary](Json.parse(text)).get
+          }
     } yield {
       val fitsKeywordDialog = FitsKeywordDialog(fitsDict, ComponentLinkSelectionHandler)
       mainContent.setContent(fitsKeywordDialog, "FITS Dictionary")

icd-web-client/src/main/scala/icd/web/client/NavbarItem.scala

@@ -68,8 +68,10 @@ object NavbarItem {
  * @param labelStr the label to display
  * @param tip the tool tip to display when hovering over the item
  * @param listener called when the item is clicked with (orientation, fontSize)
+ * @param showDocumentNumber if true, show the  Document Number field
  */
-case class NavbarPdfItem(labelStr: String, tip: String, listener: PdfOptions => Unit) extends Displayable {
+case class NavbarPdfItem(labelStr: String, tip: String, listener: PdfOptions => Unit, showDocumentNumber: Boolean)
+    extends Displayable {
   private def pdfModalListener(): Unit = {
     val orientation = document
       .querySelectorAll(s"input[name='orientation$labelStr']:checked")
@@ -98,9 +100,28 @@ case class NavbarPdfItem(labelStr: String, tip: String, listener: PdfOptions =>
       .toList
       .head
       .toBoolean
+    val documentNumber =
+      if (showDocumentNumber)
+        document
+          .querySelectorAll(s"input[name='documentNumber$labelStr']")
+          .map(elem => elem.asInstanceOf[HTMLInputElement].value)
+          .toList
+          .head
+      else ""
 
     val expandedLinkIds = if (details) Nil else getExpandedIds
-    listener(PdfOptions(orientation, fontSize, lineHeight, paperSize, details, expandedLinkIds, processMarkdown = true))
+    listener(
+      PdfOptions(
+        orientation,
+        fontSize,
+        lineHeight,
+        paperSize,
+        details,
+        expandedLinkIds,
+        processMarkdown = true,
+        documentNumber = documentNumber
+      )
+    )
   }
 
   // Finds all button items with aria-expanded=true, then gets the "name" attr of the following "a" element.
@@ -121,6 +142,7 @@ case class NavbarPdfItem(labelStr: String, tip: String, listener: PdfOptions =>
   // Makes the popup with options for generating the PDF
   private def makePdfModal(): JsDom.TypedTag[Div] = {
     import scalatags.JsDom.all._
+    val docNumCls = if (showDocumentNumber) "docNum" else "d-none"
     div(cls := "modal fade", id := s"pdfModal$labelStr", tabindex := "-1", role := "dialog", style := "padding-top: 130px")(
       div(cls := "modal-dialog")(
         div(cls := "modal-content")(
@@ -158,7 +180,11 @@ case class NavbarPdfItem(labelStr: String, tip: String, listener: PdfOptions =>
                 cls := "form-check",
                 input(`type` := "radio", cls := "form-check-input", name := s"details$labelStr", value := "false"),
                 label(cls := "form-check-label", "Include only the details that are expanded in the HTML view")
-              )
+              ),
+              hr(cls := docNumCls),
+              p(cls := docNumCls),
+              h5(cls := docNumCls, s"Document Number:"),
+              input(cls := docNumCls, id := s"documentNumber$labelStr", name := s"documentNumber$labelStr")
             )
           ),
           div(cls := "modal-footer")(

icd-web-server/app/controllers/Application.scala

@@ -184,6 +184,7 @@ class Application @Inject() (
    * @param maybeLineHeight     line-height for HTML
    * @param maybePaperSize      Letter, Legal, A4, A3, default: Letter
    * @param maybeDetails        If true, the PDF lists all detailed info, otherwise only the expanded rows in web app
+   * @param documentNumber      optional document number to include in PDF under subtitle
    */
   def icdAsPdf(
       subsystem: String,
@@ -197,7 +198,8 @@ class Application @Inject() (
       maybeFontSize: Option[Int],
       maybeLineHeight: Option[String],
       maybePaperSize: Option[String],
-      maybeDetails: Option[Boolean]
+      maybeDetails: Option[Boolean],
+      documentNumber: Option[String]
   ): Action[AnyContent] =
     Action.async { implicit request =>
       val expandedIds =
@@ -214,7 +216,15 @@ class Application @Inject() (
           maybeTargetVersion,
           maybeTargetComponent,
           maybeIcdVersion,
-          PdfOptions(maybeOrientation, maybeFontSize, maybeLineHeight, maybePaperSize, maybeDetails, expandedIds),
+          PdfOptions(
+            maybeOrientation,
+            maybeFontSize,
+            maybeLineHeight,
+            maybePaperSize,
+            maybeDetails,
+            expandedIds,
+            documentNumber = documentNumber.getOrElse("")
+          ),
           _
         )
       )
@@ -239,6 +249,7 @@ class Application @Inject() (
    * @param maybeLineHeight  line-height for HTML
    * @param maybePaperSize   Letter, Legal, A4, A3, default: Letter
    * @param maybeDetails     If true, the PDF lists all detailed info, otherwise only the expanded rows in web app
+   * @param documentNumber      optional document number to include in PDF under subtitle
    */
   def apiAsPdf(
       subsystem: String,
@@ -250,7 +261,8 @@ class Application @Inject() (
       maybeFontSize: Option[Int],
       maybeLineHeight: Option[String],
       maybePaperSize: Option[String],
-      maybeDetails: Option[Boolean]
+      maybeDetails: Option[Boolean],
+      documentNumber: Option[String]
   ) =
     Action.async { implicit request =>
       val expandedIds =
@@ -264,7 +276,15 @@ class Application @Inject() (
           maybeComponent,
           searchAll,
           clientApi,
-          PdfOptions(maybeOrientation, maybeFontSize, maybeLineHeight, maybePaperSize, maybeDetails, expandedIds),
+          PdfOptions(
+            maybeOrientation,
+            maybeFontSize,
+            maybeLineHeight,
+            maybePaperSize,
+            maybeDetails,
+            expandedIds,
+            documentNumber = documentNumber.getOrElse("")
+          ),
           _
         )
       )

icd-web-server/conf/routes

@@ -27,16 +27,16 @@ GET         /componentInfo/:subsystem                   controllers.Application.
 GET         /icdComponentInfo/:subsystem/:target        controllers.Application.icdComponentInfo(subsystem, version: Option[String], component: Option[String], target, targetVersion: Option[String], targetComponent: Option[String])
 
 # Gets the PDF for the given ICD
-GET         /icdAsPdf/:subsystem/:target                controllers.Application.icdAsPdf(subsystem, version: Option[String], component: Option[String], target, targetVersion: Option[String], targetComponent: Option[String], icdVersion: Option[String], orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean])
+GET         /icdAsPdf/:subsystem/:target                controllers.Application.icdAsPdf(subsystem, version: Option[String], component: Option[String], target, targetVersion: Option[String], targetComponent: Option[String], icdVersion: Option[String], orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean], documentNumber: Option[String])
 
 # Gets the PDF for the given ICD (using POST to pass list of expanded row ids)
-POST        /icdAsPdf/:subsystem/:target                controllers.Application.icdAsPdf(subsystem, version: Option[String], component: Option[String], target, targetVersion: Option[String], targetComponent: Option[String], icdVersion: Option[String], orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean])
+POST        /icdAsPdf/:subsystem/:target                controllers.Application.icdAsPdf(subsystem, version: Option[String], component: Option[String], target, targetVersion: Option[String], targetComponent: Option[String], icdVersion: Option[String], orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean], documentNumber: Option[String])
 
 # Gets the PDF for the given subsystem API
-GET         /apiAsPdf/:subsystem                        controllers.Application.apiAsPdf(subsystem, version: Option[String], component: Option[String], searchAll: Option[Boolean], clientApi: Option[Boolean], orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean])
+GET         /apiAsPdf/:subsystem                        controllers.Application.apiAsPdf(subsystem, version: Option[String], component: Option[String], searchAll: Option[Boolean], clientApi: Option[Boolean], orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean], documentNumber: Option[String])
 
 # Gets the PDF for the given subsystem API (using POST to pass list of expanded row ids)
-POST        /apiAsPdf/:subsystem                        controllers.Application.apiAsPdf(subsystem, version: Option[String], component: Option[String], searchAll: Option[Boolean], clientApi: Option[Boolean], orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean])
+POST        /apiAsPdf/:subsystem                        controllers.Application.apiAsPdf(subsystem, version: Option[String], component: Option[String], searchAll: Option[Boolean], clientApi: Option[Boolean], orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean], documentNumber: Option[String])
 
 # Gets the PDF for the FITS keywords
 GET         /fitsDictionaryAsPdf/:tag                   controllers.Application.fitsDictionaryAsPdf(tag, orientation: Option[String], fontSize: Option[Int], lineHeight: Option[String], paperSize: Option[String], details: Option[Boolean])

icd-web-shared/src/main/scala/icd/web/shared/PdfOptions.scala

@@ -7,10 +7,10 @@ object PdfOptions {
   val defaultPaperSize   = "Letter"
   val defaultDetails     = true
 
-  val orientations = List("landscape", "portrait")
-  val fontSizes    = List(10, 12, 14, 16)
-  val lineHeights  = List("1.6", "1.4", "1.2", "1.0")
-  val paperSizes   = List("Letter", "Legal", "A4", "A3")
+  val orientations: List[String] = List("landscape", "portrait")
+  val fontSizes: List[Int] = List(10, 12, 14, 16)
+  val lineHeights: List[String] = List("1.6", "1.4", "1.2", "1.0")
+  val paperSizes: List[String] = List("Letter", "Legal", "A4", "A3")
 
   def apply(
       maybeOrientation: Option[String] = None,
@@ -19,7 +19,8 @@ object PdfOptions {
       maybePaperSize: Option[String] = None,
       maybeDetails: Option[Boolean] = None,
       expandedIds: List[String] = Nil,
-      processMarkdown: Boolean = true
+      processMarkdown: Boolean = true,
+      documentNumber: String = ""
   ): PdfOptions =
     PdfOptions(
       maybeOrientation.getOrElse(defaultOrientation),
@@ -28,7 +29,8 @@ object PdfOptions {
       maybePaperSize.getOrElse(defaultPaperSize),
       maybeDetails.getOrElse(defaultDetails),
       expandedIds,
-      processMarkdown
+      processMarkdown,
+      documentNumber
     )
 }
 
@@ -47,5 +49,7 @@ case class PdfOptions(
     // List of ids for expanded details
     expandedIds: List[String],
     // If true (default), process markdown in text, otherwise don't (set to false if you don't need the descriptions)
-    processMarkdown: Boolean
+    processMarkdown: Boolean,
+    // If not empty, display the string at the start of the PDF document (after the title/subtitle)
+    documentNumber: String
 )