Category README generation

Issue: RiverBench/RiverBench#62

src/main/scala/commands/CategoryDocGenCommand.scala

@@ -26,7 +26,7 @@ object CategoryDocGenCommand extends Command:
       RDF.`type`,
     ),
     hidePropsInLevel = Seq(
-      (1, RDF.`type`), // Always the same
+      (2, RDF.`type`), // Always the same
     ),
     defaultPropGroup = Some("General information"),
     startHeadingLevel = 2,
@@ -57,18 +57,48 @@ object CategoryDocGenCommand extends Command:
 
   private def categoryDocGen(version: String, catRes: Resource, ontologies: Model, repoDir: Path, outDir: Path): Unit =
     val title = RdfUtil.getString(catRes, RdfUtil.dctermsTitle).get
-    val description = Files.readString(repoDir.resolve("doc/index.md")) + "\n\n## Metadata\n"
-    val builder = new DocBuilder(ontologies, catTaskDocOpt)
+    val description = RdfUtil.getString(catRes, RdfUtil.dctermsDescription).get
+    val catOpt = catTaskDocOpt.copy(
+      hidePropsInLevel = catTaskDocOpt.hidePropsInLevel ++ Seq((2, RdfUtil.dctermsDescription))
+    )
+    val builder = new DocBuilder(ontologies, catOpt)
     val catDoc = builder.build(
-      title,
-      description + rdfInfo(s"${AppConfig.CiWorker.baseCategoryUrl}$version"),
+      "Metadata",
+      rdfInfo(s"${AppConfig.CiWorker.baseCategoryUrl}$version"),
       catRes
     )
     val targetDir = outDir.resolve("category")
     targetDir.toFile.mkdirs()
-    Files.writeString(targetDir.resolve("index.md"), catDoc.toMarkdown)
+    Files.writeString(
+      targetDir.resolve("index.md"),
+      f"# $title\n\n$description\n\n" + catDoc.toMarkdown
+    )
     DocFileUtil.copyDocs(repoDir.resolve("doc"), targetDir, Seq("index.md"))
 
+    // Do the README
+    if version == "dev" then
+      println("Generating README...")
+      val docReadme = builder.build("Metadata", "", catRes)
+      val id = RdfUtil.getString(catRes, RdfUtil.dctermsIdentifier).get
+      val websiteLink = s"${AppConfig.CiWorker.baseCategoryUrl}$id/$version"
+      val readmeIntro =
+        f"""# $title
+           |
+           |${MarkdownUtil.readmeHeader("category-" + id)}
+           |
+           |*This README is a snapshot of documentation for the latest development version of the benchmark category.
+           |Full documentation for all versions can be found [on the website]($websiteLink).*
+           |
+           |$description
+           |
+           |""".stripMargin
+      Files.writeString(
+        targetDir.resolve("README.md"),
+        readmeIntro + docReadme.toMarkdown
+      )
+    else
+      print(f"Version is $version, not generating README.")
+
 
   private def taskDocGen(ontologies: Model, repoDir: Path, metadataOutDir: Path, outDir: Path, version: String): Unit =
     val taskDocBuilder = new DocBuilder(ontologies, catTaskDocOpt)
@@ -79,16 +109,18 @@ object CategoryDocGenCommand extends Command:
         val taskM = RDFDataMgr.loadModel(metadataOutDir.resolve(f"tasks/task-$taskName.ttl").toString)
         val taskRes = taskM.listSubjectsWithProperty(RDF.`type`, RdfUtil.Task).next.asResource
         val title = RdfUtil.getString(taskRes, RdfUtil.dctermsTitle) getOrElse taskName
-
-        val description = Files.readString(f.toPath.resolve("index.md")) + "\n\n## Metadata\n"
+        val description = Files.readString(f.toPath.resolve("index.md"))
         val taskDoc = taskDocBuilder.build(
-          title,
-          description + rdfInfo(s"${AppConfig.CiWorker.baseTaskUrl}$taskName/$version"),
+          "Metadata",
+          rdfInfo(s"${AppConfig.CiWorker.baseTaskUrl}$taskName/$version"),
           taskRes
         )
         val targetDir = outDir.resolve(f"tasks/$taskName")
         targetDir.toFile.mkdirs()
-        Files.writeString(targetDir.resolve("index.md"), taskDoc.toMarkdown)
+        Files.writeString(
+          targetDir.resolve("index.md"),
+          f"# $title\n\n$description\n\n" + taskDoc.toMarkdown
+        )
 
         DocFileUtil.copyDocs(f.toPath, targetDir, Seq("index.md"))
       })

src/main/scala/commands/DatasetDocGenCommand.scala

@@ -2,7 +2,7 @@ package io.github.riverbench.ci_worker
 package commands
 
 import util.doc.{DocBuilder, DocFileUtil, MarkdownUtil}
-import util.{Constants, ElementType, MetadataInfo, MetadataReader, RdfIoUtil, RdfUtil}
+import util.*
 
 import org.apache.jena.rdf.model.Property
 import org.apache.jena.riot.RDFDataMgr
@@ -92,27 +92,13 @@ object DatasetDocGenCommand extends Command:
       val docReadme = docBuilderReadme.build(title, mi.description + readmeIntro(landingPage), mi.datasetRes)
       Files.writeString(
         outputDir.resolve("README.md"),
-        readmeHeader(mi.identifier) + "\n\n" + docReadme.toMarkdown
+        MarkdownUtil.readmeHeader("dataset" + mi.identifier) + "\n\n" + docReadme.toMarkdown
       )
       println("Generated README.md")
     else
       println(f"Version is $version – not generating README.md")
   }
 
-  private def readmeHeader(id: String): String =
-    f"""<!--
-       |--
-       |-- THIS FILE IS AUTOGENERATED. DO NOT EDIT.
-       |-- Please edit the metadata.ttl file instead. The documentation
-       |-- will be regenerated by the CI.
-       |--
-       |-- You can place additional docs in the /doc directory. Remember to link
-       |-- to them from the description in the metadata.ttl file.
-       |--
-       |-->
-       |[![.github/workflows/release.yaml](${Constants.baseRepoUrl}/dataset-$id/actions/workflows/release.yaml/badge.svg?event=push)](${Constants.baseRepoUrl}/dataset-$id/actions/workflows/release.yaml)
-       |""".stripMargin
-
   private def readmeIntro(websiteLink: String): String =
     f"""
        |

src/main/scala/util/doc/MarkdownUtil.scala

@@ -1,6 +1,8 @@
 package io.github.riverbench.ci_worker
 package util.doc
 
+import util.Constants
+
 object MarkdownUtil:
   private val sizePrefixes = Seq("B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")
 
@@ -39,3 +41,17 @@ object MarkdownUtil:
   def formatMetadataLinks(baseUrl: String, suffix: String = ""): String =
     f"**[Turtle]($baseUrl.ttl$suffix)**, **[N-Triples]($baseUrl.nt$suffix)**, " +
       f"**[RDF/XML]($baseUrl.rdf$suffix)**, **[Jelly]($baseUrl.jelly$suffix)**"
+
+  def readmeHeader(repoName: String): String =
+    f"""<!--
+       |--
+       |-- THIS FILE IS AUTOGENERATED. DO NOT EDIT.
+       |-- Please edit the metadata.ttl file instead. The documentation
+       |-- will be regenerated by the CI.
+       |--
+       |-- You can place additional docs in the /doc directory. Remember to link
+       |-- to them from the description in the metadata.ttl file.
+       |--
+       |-->
+       |[![.github/workflows/release.yaml](${Constants.baseRepoUrl}/$repoName/actions/workflows/release.yaml/badge.svg?event=push)](${Constants.baseRepoUrl}/$repoName/actions/workflows/release.yaml)
+       |""".stripMargin