From 5a99cb8af865c5ebbbec88a5db652c2b803d82f4 Mon Sep 17 00:00:00 2001 From: Simon Parten Date: Wed, 3 Jan 2024 23:54:01 +0100 Subject: [PATCH] Some doc improvements --- .gitignore | 3 +- build.sc | 96 ++++++++++++++++--- mill | 2 +- scautable/js/src/jsSpecific.scala | 2 +- scautable/jvm/src/jvmSpecific.scala | 5 +- scautable/src/package.scala | 22 ++--- scautable/test/jvm/src/testJvm.scala | 2 +- scautable/test/src/test.scala | 4 +- ...tarted.mdoc.md => Getting_Started.mdoc.md} | 10 +- site/docs/_docs/index.md | 18 ++++ 10 files changed, 126 insertions(+), 38 deletions(-) rename site/docs/_docs/{GettingStarted.mdoc.md => Getting_Started.mdoc.md} (84%) create mode 100644 site/docs/_docs/index.md diff --git a/.gitignore b/.gitignore index eccbd2c..770b5fe 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,5 @@ .scala-build .metals .bsp -out \ No newline at end of file +out +.bloop \ No newline at end of file diff --git a/build.sc b/build.sc index 3a09d52..0c151f2 100644 --- a/build.sc +++ b/build.sc @@ -1,14 +1,18 @@ import $ivy.`com.github.lolgab::mill-crossplatform::0.2.4` -import $ivy.`io.github.quafadas::mill_scala3_site_mdoc::0.0.9` +import $ivy.`io.github.quafadas::millSite::0.0.11-9-25cd8f` import $ivy.`de.tototec::de.tobiasroeser.mill.vcs.version::0.4.0` import de.tobiasroeser.mill.vcs.version._ import com.github.lolgab.mill.crossplatform._ import mill._, mill.scalalib._, mill.scalajslib._, mill.scalanativelib._ -import millSite.SiteModule +import io.github.quafadas.millSite.SiteModule +import io.github.quafadas.millSite.QuickChange import mill._, scalalib._, publish._ +import mill.api.Result + + trait Common extends ScalaModule with PublishModule { def scalaVersion = "3.3.1" @@ -65,17 +69,87 @@ object scautable extends CrossPlatform { object site extends SiteModule { - def latestVersion = T{VcsVersion.vcsState().lastTag.getOrElse("0.0.0").replace("v", "")} - def scalaVersion = scautable.jvm.scalaVersion - override def moduleDeps = Seq( scautable.jvm, scautable.js ) + override def moduleDeps = Seq(scautable.jvm) - override def scalaDocOptions = super.scalaDocOptions() ++ Seq( - "-scastie-configuration", s"""libraryDependencies += "io.github.quafadas" %% "scautable" % "${latestVersion()}" """, - "-project", "scautable", - "-project-version", latestVersion(), - s"-social-links:github::${scautable.jvm.pomSettings().url}" - ) + private def fixAssets(docFile: os.Path) = { + if (docFile.ext == "md") { + val fixyFixy = os.read(docFile).replace("../_assets/", "") + os.write.over(docFile, fixyFixy.getBytes()) + } + } + + + override def docOnlyGen: T[QuickChange] = T { + val md = mdoc().path + val origDocs = mdocSourceDir().path + val javadocDir = T.dest / "javadoc" + os.makeDir.all(javadocDir) + val combinedStaticDir = T.dest / "static" + os.makeDir.all(combinedStaticDir) + + // copy mdoccd files in + for { + aDoc <- os.walk(md) + rel = (combinedStaticDir / aDoc.subRelativeTo(md)) + } { + // println(rel) + os.copy.over(aDoc, rel) + fixAssets(rel) // pure filth, report as bug? + } + + // copy all other doc files + for { + aDoc <- os.walk(origDocs) + rel = (combinedStaticDir / aDoc.subRelativeTo(mdocDir)); + if !os.exists(rel) + } { + os.copy(aDoc, rel) + // fixAssets(rel) // pure filth, report as bug? + } + + // if (os.exists(assetDir)) { + // os.copy(assetDir, javadocDir, mergeFolders = true, replaceExisting = true) + // } + + val compileCp = compileCpArg + val options = Seq( + "-d", + javadocDir.toNIO.toString, + "-siteroot", + combinedStaticDir.toNIO.toString + ) + + val localCp = Lib + .findSourceFiles(Seq(fakeSource().classes), Seq("tasty")) + .map(_.toString()) // fake api to skip potentially slow doc generation + + zincWorker() + .worker() + .docJar( + scalaVersion(), + scalaOrganization(), + scalaDocClasspath(), + scalacPluginClasspath(), + options ++ compileCpArg() ++ scalaDocOptions() + ++ localCp + ) match { + case true => + Result.Success( + QuickChange( + os.walk(javadocDir / "docs") + .filter(os.isFile) + .map(PathRef(_)) + .toSeq, + PathRef(javadocDir, true) + ) + ) + case false => + Result.Failure( + s"""Documentation generatation failed. Cause could include be no sources files in : ${sources()} or no doc files in ${docSources()}, or an error message printed above... """ + ) + } + } } \ No newline at end of file diff --git a/mill b/mill index 03e5c21..936ad0d 100755 --- a/mill +++ b/mill @@ -238,4 +238,4 @@ unset MILL_REPO_URL # We don't quote MILL_FIRST_ARG on purpose, so we can expand the empty value without quotes # shellcheck disable=SC2086 -exec "${MILL}" $MILL_FIRST_ARG -D "mill.main.cli=${MILL_MAIN_CLI}" "$@" \ No newline at end of file +exec "${MILL}" $MILL_FIRST_ARG -D "mill.main.cli=${MILL_MAIN_CLI}" -j 0 "$@" \ No newline at end of file diff --git a/scautable/js/src/jsSpecific.scala b/scautable/js/src/jsSpecific.scala index 92fdd70..f7dcb3b 100644 --- a/scautable/js/src/jsSpecific.scala +++ b/scautable/js/src/jsSpecific.scala @@ -1,4 +1,4 @@ -package scautable +package io.github.quafadas.scautable trait PlatformSpecific { diff --git a/scautable/jvm/src/jvmSpecific.scala b/scautable/jvm/src/jvmSpecific.scala index 3bb2841..7838352 100644 --- a/scautable/jvm/src/jvmSpecific.scala +++ b/scautable/jvm/src/jvmSpecific.scala @@ -1,8 +1,7 @@ -package scautable +package io.github.quafadas.scautable - -import scautable.HtmlTableRender import java.awt.Desktop +import io.github.quafadas.scautable.scautable.HtmlTableRender // import almond.api.JupyterApi // import almond.interpreter.api.DisplayData // import almond.api.JupyterAPIHolder.value diff --git a/scautable/src/package.scala b/scautable/src/package.scala index 20a9e3e..5fc7d51 100644 --- a/scautable/src/package.scala +++ b/scautable/src/package.scala @@ -1,4 +1,4 @@ -package scautable +package io.github.quafadas.scautable import scalatags.Text.all.* import scala.deriving.Mirror import scala.compiletime.erasedValue @@ -13,7 +13,7 @@ import scalatags.Text.TypedTag object scautable extends PlatformSpecific { // Aggressively copy-pasta-d from here; https://blog.philipp-martini.de/blog/magic-mirror-scala3/ - inline def getTypeclassInstances[A <: Tuple]: List[HtmlTableRender[Any]] = + protected inline def getTypeclassInstances[A <: Tuple]: List[HtmlTableRender[Any]] = inline erasedValue[A] match { case _: EmptyTuple => Nil case _: (head *: tail) => @@ -28,11 +28,11 @@ object scautable extends PlatformSpecific { } // helper method like before - inline def summonInstancesHelper[A](using m: Mirror.Of[A]) = + protected inline def summonInstancesHelper[A](using m: Mirror.Of[A]) = getTypeclassInstances[m.MirroredElemTypes] // this traits can just be copy/pasted or reside in a library - trait EasyDerive[TC[_]] { + protected trait EasyDerive[TC[_]] { final def apply[A](using tc: TC[A]): TC[A] = tc case class CaseClassElement[A, B]( @@ -59,14 +59,14 @@ object scautable extends PlatformSpecific { getElement: A => SealedElement[A, _] ) - inline def getInstances[A <: Tuple]: List[TC[Any]] = + protected inline def getInstances[A <: Tuple]: List[TC[Any]] = inline erasedValue[A] match { case _: EmptyTuple => Nil case _: (t *: ts) => summonInline[TC[t]].asInstanceOf[TC[Any]] :: getInstances[ts] } - inline def getElemLabels[A <: Tuple]: List[String] = + protected inline def getElemLabels[A <: Tuple]: List[String] = inline erasedValue[A] match { case _: EmptyTuple => Nil case _: (t *: ts) => constValue[t].toString :: getElemLabels[ts] @@ -200,14 +200,14 @@ object scautable extends PlatformSpecific { } } - def deriveTableRow[A](a: A)(using instance: HtmlTableRender[A]) = + protected def deriveTableRow[A](a: A)(using instance: HtmlTableRender[A]) = instance.tableRow(a) - def deriveTableHeader[A](a: A)(using instance: HtmlTableRender[A]) = + protected def deriveTableHeader[A](a: A)(using instance: HtmlTableRender[A]) = println("deriveTableHeader") tr(instance.tableRow(a)) - inline def getElemLabels[A <: Tuple]: List[String] = + protected inline def getElemLabels[A <: Tuple]: List[String] = inline erasedValue[A] match { case _: EmptyTuple => Nil // stop condition - the tuple is empty case _: (head *: tail) => // yes, in scala 3 we can match on tuples head and tail to deconstruct them step by step @@ -218,11 +218,11 @@ object scautable extends PlatformSpecific { headElementLabel :: tailElementLabels // concat head + tail } - inline def tableHeader[A](using m: Mirror.Of[A]) = + protected inline def tableHeader[A](using m: Mirror.Of[A]) = val elemLabels = getElemLabels[m.MirroredElemLabels] tr(elemLabels.map(th(_))) - inline def deriveCaseClass[A](using m: Mirror.ProductOf[A]) = + protected inline def deriveCaseClass[A](using m: Mirror.ProductOf[A]) = new HtmlTableRender[A] { override def tableHeader(a: A) = diff --git a/scautable/test/jvm/src/testJvm.scala b/scautable/test/jvm/src/testJvm.scala index 4747ef5..2626de9 100644 --- a/scautable/test/jvm/src/testJvm.scala +++ b/scautable/test/jvm/src/testJvm.scala @@ -1,4 +1,4 @@ -package scautable +package io.github.quafadas.scautable import scalatags.Text.all.* import java.time.LocalDate diff --git a/scautable/test/src/test.scala b/scautable/test/src/test.scala index 3568f6f..0bd0272 100644 --- a/scautable/test/src/test.scala +++ b/scautable/test/src/test.scala @@ -1,4 +1,4 @@ -package scautable +package io.github.quafadas.scautable import scalatags.Text.all.* import java.time.LocalDate @@ -74,7 +74,7 @@ class MySuite extends munit.FunSuite { test("Compound Product Seq") { case class SeqMe(s: Seq[(Int, String)]) - val startSeq = SeqMe(Seq((1, "happy"), (2, "land"))) + val startSeq = SeqMe(Seq((1, "happy"), (2, "land"))) assertEquals( """
s
_1_2
1happy
2land
""", scautable(startSeq, true).toString() diff --git a/site/docs/_docs/GettingStarted.mdoc.md b/site/docs/_docs/Getting_Started.mdoc.md similarity index 84% rename from site/docs/_docs/GettingStarted.mdoc.md rename to site/docs/_docs/Getting_Started.mdoc.md index baf6d79..72a1ad0 100644 --- a/site/docs/_docs/GettingStarted.mdoc.md +++ b/site/docs/_docs/Getting_Started.mdoc.md @@ -1,8 +1,4 @@ ---- -title: Getting Started ---- -# Import ```scala @@ -13,7 +9,7 @@ title: Getting Started # Elevator Pitch ```scala mdoc -import scautable.{*, given} +import io.github.quafadas.scautable.{*, given} case class ScauTest(anInt: Int, aString: String) scautable( @@ -22,10 +18,10 @@ scautable( ).toString() ``` -On the JVM in particular, the ability to pop it open in the browser, see and search the actual data... can be useful. Particularly if you're working with a lot of mesy, csv data for example. +On the JVM in particular, the ability to pop it open in the browser, see and search the actual data... can be useful. Particularly if you're working with a lot of messy, csv data for example. ```scala -import scautable.{*, given} +import io.github.quafadas.scautable.{*, given} case class ScauTest(anInt: Int, aString: String) val soComplex = Seq(ScauTest(1, "one"), ScauTest(2, "two")) diff --git a/site/docs/_docs/index.md b/site/docs/_docs/index.md new file mode 100644 index 0000000..d8364a1 --- /dev/null +++ b/site/docs/_docs/index.md @@ -0,0 +1,18 @@ +Auto Magically generate and view searchablehtml tables a `Seq[A]` + + +```scala + +//> using dep io.github.quafadas::scautable:{{projectVersion}} + +``` + +```scala +import io.github.quafadas.scautable.{*, given} + +case class ScauTest(anInt: Int, aString: String) +scautable( + Seq(ScauTest(1, "one"), ScauTest(2, "two")), + true +).toString() +``` \ No newline at end of file