Merge pull request #10092 from romanowski/scala3doc/migration

Migrate Scala3doc repo to Dotty

Author: abgruszecki

.github/workflows/ci.yaml

@@ -2,7 +2,15 @@ name: Dotty CI
 
 on:
   push:
+    paths-ignore:
+      # Do not run everything on changes only in docs
+      - 'scala3doc/**' 
+      - 'scala3doc-testcases/**'
   pull_request:
+    paths-ignore:
+      # Do not run everything on changes only in docs
+      - 'scala3doc/**' 
+      - 'scala3doc-testcases/**'
   schedule:
     - cron: '0 3 * * *'  # Every day at 3 AM
 

.github/workflows/scala3doc.yaml

@@ -0,0 +1,46 @@
+name: CI for Scala3doc
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container: lampepfl/dotty:2020-04-24
+
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@v2
+
+      - name: Cache Coursier
+        uses: actions/cache@v1
+        with:
+          path: ~/.cache/coursier
+          key: sbt-coursier-cache
+      - name: Cache SBT
+        uses: actions/cache@v1
+        with:
+          path: ~/.sbt
+          key: sbt-${{ hashFiles('**/build.sbt') }}
+
+      - name: Set up JDK 11
+        uses: actions/setup-java@v1
+        with:
+          java-version: 11
+
+      - name: Compile and test
+        run: ./project/scripts/sbt scala3doc/test
+
+      - name: Locally publish self
+        run: ./project/scripts/sbt scala3doc/publishLocal
+
+      - name: Generate test documentation
+        run: ./project/scripts/sbt scala3doc/generateSelfDocumentation
+
+      - name: Generate Scala 3 documentation
+        run: ./project/scripts/sbt scala3doc/generateScala3Documentation
+
+      - name: Generate documentation for example project using dotty-sbt
+        run: ./project/scripts/sbt "sbt-dotty/scripted sbt-dotty/scala3doc"

build.sbt

@@ -20,6 +20,8 @@ val `stdlib-bootstrapped-tasty-tests` = Build.`stdlib-bootstrapped-tasty-tests`
 val `tasty-core` = Build.`tasty-core`
 val `tasty-core-bootstrapped` = Build.`tasty-core-bootstrapped`
 val `tasty-core-scala2` = Build.`tasty-core-scala2`
+val scala3doc = Build.scala3doc
+val `scala3doc-testcases` = Build.`scala3doc-testcases`
 val `scala3-bench-run` = Build.`scala3-bench-run`
 val dist = Build.dist
 val `community-build` = Build.`community-build`

project/Build.scala

@@ -213,6 +213,12 @@ object Build {
     }
   )
 
+  lazy val disableDocSetting =
+    // Disable scaladoc generation, it's way too slow and we'll replace it
+    // by dottydoc anyway. We still publish an empty -javadoc.jar to make
+    // sonatype happy.
+      sources in (Compile, doc) := Seq()
+
   lazy val commonSettings = publishSettings ++ Seq(
     scalaSource       in Compile    := baseDirectory.value / "src",
     scalaSource       in Test       := baseDirectory.value / "test",
@@ -221,11 +227,6 @@ object Build {
     resourceDirectory in Compile    := baseDirectory.value / "resources",
     resourceDirectory in Test       := baseDirectory.value / "test-resources",
 
-    // Disable scaladoc generation, it's way too slow and we'll replace it
-    // by dottydoc anyway. We still publish an empty -javadoc.jar to make
-    // sonatype happy.
-    sources in (Compile, doc) := Seq(),
-
     // Prevent sbt from rewriting our dependencies
     scalaModuleInfo ~= (_.map(_.withOverrideScalaVersion(false))),
 
@@ -244,7 +245,8 @@ object Build {
     crossPaths := false,
     // Do not depend on the Scala library
     autoScalaLibrary := false,
-    excludeFromIDE := true
+    excludeFromIDE := true,
+    disableDocSetting
   )
 
   // Settings used when compiling dotty (both non-bootstrapped and bootstrapped)
@@ -258,6 +260,8 @@ object Build {
     moduleName ~= { _.stripSuffix("-scala2") },
     version := dottyVersion,
     target := baseDirectory.value / ".." / "out" / "scala-2" / name.value,
+
+    disableDocSetting
   )
 
   // Settings used when compiling dotty with the reference compiler
@@ -267,6 +271,8 @@ object Build {
     version := dottyNonBootstrappedVersion,
     scalaVersion := referenceVersion,
     excludeFromIDE := true,
+
+    disableDocSetting
   )
 
   // Settings used when compiling dotty with a non-bootstrapped dotty
@@ -328,6 +334,8 @@ object Build {
     },
     // sbt-dotty defines `scalaInstance in doc` so we need to override it manually
     scalaInstance in doc := scalaInstance.value,
+
+    disableDocSetting,
   )
 
   lazy val commonBenchmarkSettings = Seq(
@@ -1153,6 +1161,14 @@ object Build {
   lazy val `scala3-bench-bootstrapped` = project.in(file("bench")).asDottyBench(Bootstrapped)
   lazy val `scala3-bench-run` = project.in(file("bench-run")).asDottyBench(Bootstrapped)
 
+  val testcasesOutputDir = taskKey[String]("Root directory where tests classses are generated")
+  val testcasesSourceRoot = taskKey[String]("Root directory where tests sources are generated")
+  val generateSelfDocumentation = taskKey[Unit]("Generate example documentation")
+  val generateScala3Documentation = taskKey[Unit]("Generate documentation for dotty lib")
+  val generateTestcasesDocumentation  = taskKey[Unit]("Generate documentation for testcases, usefull for debugging tests")
+  lazy val `scala3doc` = project.in(file("scala3doc")).asScala3doc
+  lazy val `scala3doc-testcases` = project.in(file("scala3doc-testcases")).asScala3docTestcases
+
   // sbt plugin to use Dotty in your own build, see
   // https://github.com/lampepfl/scala3-example-project for usage.
   lazy val `sbt-dotty` = project.in(file("sbt-dotty")).
@@ -1192,6 +1208,7 @@ object Build {
         publishLocal in `scala3-staging`,
         publishLocal in `scala3-tasty-inspector`,
         publishLocal in `scala3-doc-bootstrapped`,
+        publishLocal in `scala3doc`,
         publishLocal in `scala3-bootstrapped` // Needed because sbt currently hardcodes the dotty artifact
       ).evaluated
     )
@@ -1393,7 +1410,7 @@ object Build {
     def asDottyRoot(implicit mode: Mode): Project = project.withCommonSettings.
       aggregate(`scala3-interfaces`, dottyLibrary, dottyCompiler, tastyCore, dottyDoc, `scala3-sbt-bridge`).
       bootstrappedAggregate(`scala3-language-server`, `scala3-staging`, `scala3-tasty-inspector`,
-        `scala3-library-bootstrappedJS`).
+        `scala3-library-bootstrappedJS`, scala3doc).
       dependsOn(tastyCore).
       dependsOn(dottyCompiler).
       dependsOn(dottyLibrary).
@@ -1440,6 +1457,70 @@ object Build {
       settings(commonBenchmarkSettings).
       enablePlugins(JmhPlugin)
 
+    def asScala3doc: Project = {
+      def generateDocumentation(targets: String, name: String, outDir: String, params: String = "") = Def.taskDyn {
+          val sourceMapping = "=https://github.com/lampepfl/dotty/tree/master#L"
+          run.in(Compile).toTask(s""" -d output/$outDir -t $targets -n "$name" -s $sourceMapping $params""")
+      }
+
+      project.settings(commonBootstrappedSettings).
+        dependsOn(`scala3-compiler-bootstrapped`).
+        dependsOn(`scala3-tasty-inspector`).
+        settings(
+          // Needed to download dokka and its dependencies
+          resolvers += Resolver.jcenterRepo,
+          // Needed to download dokka-site
+          resolvers += Resolver.bintrayRepo("virtuslab", "dokka"),
+          libraryDependencies ++= Seq(
+            "com.virtuslab.dokka" % "dokka-site" % "0.1.9",
+            "com.vladsch.flexmark" % "flexmark-all" % "0.42.12",
+            "nl.big-o" % "liqp" % "0.6.7",
+            "args4j" % "args4j" % "2.33",
+
+            "org.jetbrains.dokka" % "dokka-test-api" % "1.4.10.2" % "test",
+            "com.novocode" % "junit-interface" % "0.11" % "test",
+          ),
+          Test / test := (Test / test).dependsOn(compile.in(Compile).in(`scala3doc-testcases`)).value,
+          testcasesOutputDir.in(Test) := classDirectory.in(Compile).in(`scala3doc-testcases`).value.getAbsolutePath.toString,
+          testcasesSourceRoot.in(Test) := (baseDirectory.in(`scala3doc-testcases`).value / "src").getAbsolutePath.toString,
+          Compile / mainClass := Some("dotty.dokka.Main"),
+          // There is a bug in dokka that prevents parallel tests withing the same jvm
+          fork.in(test) := true,
+          generateSelfDocumentation := Def.taskDyn {
+            generateDocumentation(classDirectory.in(Compile).value.getAbsolutePath, "scala3doc", "self", "-p documentation")
+          }.value,
+          generateScala3Documentation := Def.taskDyn {
+            val dottyJars = Seq(
+              // All projects below will be used to generated documentation for Scala 3
+              classDirectory.in(`scala3-interfaces`).in(Compile).value,
+              classDirectory.in(`tasty-core`).in(Compile).value,
+              classDirectory.in(`scala3-library`).in(Compile).value,
+              // TODO this one fails to load using TASTY
+              // classDirectory.in(`stdlib-bootstrapped`).in(Compile).value,
+            )
+            val roots = dottyJars.map(_.toString).mkString(java.io.File.pathSeparator)
+
+            if (dottyJars.isEmpty) Def.task { streams.value.log.error("Dotty lib wasn't found") }
+            else generateDocumentation(roots, "Scala 3", "stdLib", "-p dotty-docs/docs")
+          }.value,
+          generateTestcasesDocumentation := Def.taskDyn {
+            generateDocumentation(Build.testcasesOutputDir.in(Test).value, "Scala3doc testcases", "testcases")
+          }.value,
+          buildInfoKeys in Test := Seq[BuildInfoKey](
+            Build.testcasesOutputDir.in(Test),
+            Build.testcasesSourceRoot.in(Test),
+          ),
+          buildInfoPackage in Test := "dotty.dokka",
+          BuildInfoPlugin.buildInfoScopedSettings(Test),
+          BuildInfoPlugin.buildInfoDefaultSettings,
+          // Uncomment to debug dokka processing (require to run debug in listen mode on 5005 port)
+          // javaOptions.in(run) += "-agentlib:jdwp=transport=dt_socket,server=n,address=localhost:5005,suspend=y"
+        )
+    }
+
+    def asScala3docTestcases: Project =
+      project.dependsOn(`scala3-compiler-bootstrapped`).settings(commonBootstrappedSettings)
+
     def asDist(implicit mode: Mode): Project = project.
       enablePlugins(PackPlugin).
       withCommonSettings.

sbt-dotty/sbt-test/sbt-dotty/scala3doc/build.sbt

@@ -0,0 +1,3 @@
+scalaVersion := sys.props("plugin.scalaVersion")
+
+useScala3doc := true

sbt-dotty/sbt-test/sbt-dotty/scala3doc/project/plugins.sbt

@@ -0,0 +1 @@
+addSbtPlugin("ch.epfl.lamp" % "sbt-dotty" % sys.props("plugin.version"))

sbt-dotty/sbt-test/sbt-dotty/scala3doc/src/main/scala/AutoParamTupling.scala

@@ -0,0 +1,25 @@
+package example
+
+/**
+  * Automatic Tupling of Function Params: https://dotty.epfl.ch/docs/reference/other-new-features/auto-parameter-tupling.html
+  */
+object AutoParamTupling {
+
+  def test: Unit = {
+
+    /**
+      * In order to get thread safety, you need to put @volatile before lazy vals.
+      * https://dotty.epfl.ch/docs/reference/changed-features/lazy-vals.html
+      */
+    @volatile lazy val xs: List[String] = List("d", "o", "t", "t", "y")
+
+    /**
+      * Current behaviour in Scala 2.12.2 :
+      * error: missing parameter type
+      * Note: The expected type requires a one-argument function accepting a 2-Tuple.
+      * Consider a pattern matching anonymous function, `{ case (s, i) =>  ... }`
+      */
+    xs.zipWithIndex.map((s, i) => println(s"$i: $s"))
+
+  }
+}

sbt-dotty/sbt-test/sbt-dotty/scala3doc/src/main/scala/ContextQueries.scala

@@ -0,0 +1,48 @@
+package example
+
+import scala.concurrent.{ExecutionContext, Future}
+import scala.util.Try
+
+/**
+  * Context Queries:
+  * - http://dotty.epfl.ch/docs/reference/contextual/query-types.html,
+  * - https://www.scala-lang.org/blog/2016/12/07/implicit-function-types.html
+  */
+object ContextQueries /* Formerly known as Implicit Function Types */ {
+
+  object context {
+    // type alias Contextual
+    type Contextual[T] = ExecutionContext ?=> T
+
+    // sum is expanded to sum(x, y)(ctx)
+    def asyncSum(x: Int, y: Int): Contextual[Future[Int]] = Future(x + y)
+
+    def asyncMult(x: Int, y: Int)(using ctx: ExecutionContext) = Future(x * y)
+  }
+
+  object parse {
+
+    type Parseable[T] = ImpliedInstances.StringParser[T] ?=> Try[T]
+
+    def sumStrings(x: String, y: String): Parseable[Int] = {
+      val parser = implicitly[ImpliedInstances.StringParser[Int]]
+      val tryA = parser.parse(x)
+      val tryB = parser.parse(y)
+
+      for {
+        a <- tryA
+        b <- tryB
+      } yield a + b
+    }
+  }
+
+  def test: Unit = {
+    import ExecutionContext.Implicits.global
+    context.asyncSum(3, 4).foreach(println)
+    context.asyncMult(3, 4).foreach(println)
+
+    println(parse.sumStrings("3", "4"))
+    println(parse.sumStrings("3", "a"))
+  }
+
+}

sbt-dotty/sbt-test/sbt-dotty/scala3doc/src/main/scala/Conversion.scala

@@ -0,0 +1,39 @@
+package example
+
+import scala.language.implicitConversions
+
+/**
+  *  Conversions: http://dotty.epfl.ch/docs/reference/contextual/conversions.html
+  */
+object Conversion {
+
+  case class IntWrapper(a: Int) extends AnyVal
+  case class DoubleWrapper(b: Double) extends AnyVal
+
+  def convert[T, U](x: T)(using converter: Conversion[T, U]): U = converter(x)
+
+  given IntWrapperToDoubleWrapper as Conversion[IntWrapper, DoubleWrapper] = new Conversion[IntWrapper, DoubleWrapper] {
+    override def apply(i: IntWrapper): DoubleWrapper = new DoubleWrapper(i.a.toDouble)
+  }
+
+  def useConversion(using f: Conversion[IntWrapper, DoubleWrapper]) = {
+    val y: IntWrapper = new IntWrapper(4)
+    val x: DoubleWrapper = y
+    x
+  }
+
+  /* Not working anymore.
+    def useConversion(implicit f: A => B) = {
+      val y: A = ...
+      val x: B = a    // error under Dotty
+    }
+   */
+
+  def test: Unit = {
+    println(useConversion)
+    println(convert(new IntWrapper(42)))
+  }
+
+
+
+}