Split scala3 doc and migrate file layout

Now both project matches repository standard.
Test and dummy classes does not clutter scala3doc jar (are defined in test)

Author: romanowski

.github/workflows/scala3doc.yaml

@@ -33,43 +33,13 @@ jobs:
           java-version: 11
 
       - name: Compile and test
-        run: sbt compile test
+        run: sbt scala3doc/test
 
       - name: Locally publish self
-        run: sbt publishLocal
+        run: sbt scala3doc/publishLocal
 
       - name: Generate test documentation
-        run: sbt generateSelfDocumentation
-        
-      - name: Generate documentation for dotty library
-        run: sbt generateDottyLibDocumentation      
+        run: sbt scala3doc/generateSelfDocumentation
 
       - name: Generate documentation with SBT plugin
-        run: sbt example-project/doc
-
-      - name: Configure AWS Credentials
-        uses: aws-actions/configure-aws-credentials@v1
-        with:
-          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          aws-region: eu-central-1
-
-      - name: Publish all
-        run: |
-              dest=s3://scala3doc/$([ $GITHUB_REF = "master" ] && echo master || echo pr-$(echo $GITHUB_REF | cut '-d/' -f3))
-              aws s3 rm $dest
-              aws s3 sync output $dest
-
-      - name: Update gh-pages
-        run: |
-             if [ $GITHUB_REF = "refs/heads/master" ]; then
-                git config --global user.email "$(git log -1 --format=%ae)"
-                git config --global user.name "$(git log -1 --format=%an)"
-                git subtree add --prefix=our-site origin gh-pages
-                rm -r our-site/*
-                cp -r  output/self/* our-site
-                git add our-site
-                git commit -m "$(git log -1 --pretty=%B)"
-                git subtree push --prefix=our-site origin gh-pages
-             fi
-
+        run: sbt scala3doc-example-project/doc

build.sbt

@@ -20,6 +20,9 @@ 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 scala3docTest = Build.`scala3doc-test`
+// val `scala3doc-example-project` = Build.`scala3doc-example-project`
 val `scala3-bench-run` = Build.`scala3-bench-run`
 val dist = Build.dist
 val `community-build` = Build.`community-build`

project/Build.scala

@@ -1153,6 +1153,10 @@ 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)
 
+  lazy val `scala3doc` = project.in(file("scala3doc")).asScala3doc
+  lazy val `scala3doc-test` = project.in(file("scala3doc-test")).asScala3docTest
+  lazy val `scala3doc-example-project` = project.in(file("scala3doc-example-project")).asDocExampleProject
+
   // 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")).
@@ -1440,6 +1444,73 @@ object Build {
       settings(commonBenchmarkSettings).
       enablePlugins(JmhPlugin)
 
+    def commonScala3DocSettings = commonBootstrappedSettings ++ Seq(
+      scalaVersion := dottyVersion,
+      resolvers += Resolver.jcenterRepo,
+      resolvers += Resolver.bintrayRepo("kotlin", "kotlin-dev"),
+      resolvers += Resolver.bintrayRepo("virtuslab", "dokka"),
+      // hack, we cannot build documentation so we need this to publish locally
+      publishArtifact in (Compile, packageDoc) := false
+    )
+
+    def asScala3doc: Project = 
+      project.
+        settings(commonScala3DocSettings).
+        dependsOn(`scala3-compiler-bootstrapped`).
+        dependsOn(`scala3-tasty-inspector`)
+
+    def asScala3docTest: Project = 
+      project.
+        settings(commonScala3DocSettings).
+        dependsOn(`scala3doc`)
+    
+    def asDocExampleProject: Project = project.
+      settings(commonBootstrappedSettings0).
+      dependsOn(`scala3-compiler-bootstrapped`).
+      settings(
+        Compile/scalaSource := baseDirectory.value / "src/main/scala",
+        Test/scalaSource := baseDirectory.value / "src/test/scala",
+        Compile/resourceDirectory := baseDirectory.value / "src/main/resources",
+        Test/resourceDirectory := baseDirectory.value / "src/test/resources",
+
+        name := "scala3doc-example-project",
+        description := "Example SBT project that is documented using Scala3doc",
+        version := "0.1.0-SNAPSHOT",
+        scalaVersion := dottyVersion,
+
+        useScala3doc := true,
+        scala3docOptions ++= Seq("--name", "example-project"),
+        Compile / doc / target := file("out/doc/example-project"),
+
+        // we cannot set
+        doc/scalaInstance := {
+          val externalNonBootstrappedDeps = externalDependencyClasspath.in(`scala3doc`, Compile).value
+          val scalaLibrary = findArtifact(externalNonBootstrappedDeps, "scala-library")
+
+          // IMPORTANT: We need to use actual jars to form the ScalaInstance and not
+          // just directories containing classfiles because sbt maintains a cache of
+          // compiler instances. This cache is invalidated based on timestamps
+          // however this is only implemented on jars, directories are never
+          // invalidated.
+          val tastyCore = packageBin.in(`tasty-core`, Compile).value
+          val dottyLibrary = packageBin.in(`scala3-library-bootstrapped`, Compile).value
+          val dottyInterfaces = packageBin.in(`scala3-interfaces`, Compile).value
+          val dottyCompiler = packageBin.in(`scala3-compiler-bootstrapped`, Compile).value
+          val doctool = packageBin.in(`scala3doc`, Compile).value
+
+          val allJars = Seq(tastyCore, dottyLibrary, dottyInterfaces, dottyCompiler, doctool) ++ externalNonBootstrappedDeps.map(_.data)
+
+          makeScalaInstance(
+            state.value,
+            scalaVersion.value,
+            scalaLibrary,
+            dottyLibrary,
+            dottyCompiler,
+            allJars
+          )
+        },
+      )
+
     def asDist(implicit mode: Mode): Project = project.
       enablePlugins(PackPlugin).
       withCommonSettings.

scala3doc-test/build.sbt

@@ -0,0 +1,30 @@
+val dokkaVersion = "1.4.10.2"
+
+libraryDependencies ++= Seq(
+  "org.jetbrains.dokka" % "dokka-test-api" % dokkaVersion % "test", // TODO move testing utils to dokka-site
+  "com.novocode" % "junit-interface" % "0.11" % "test",
+)
+
+val testOuputDir = taskKey[String]("Root directory where tests classses are generated")
+testOuputDir := (Compile/target/classDirectory).value.getAbsolutePath.toString
+
+val testSourceRoot = taskKey[String]("Root directory where tests sources are generated")
+testSourceRoot := (baseDirectory.value / "src").getAbsolutePath.toString
+
+
+buildInfoKeys in Test := Seq[BuildInfoKey](
+  testOuputDir,
+  testSourceRoot,
+)
+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"
+
+fork.in(run) := true
+
+// There is a bug in dokka that prevents parallel tests withing the same jvm
+fork.in(test) := true
+Test / parallelExecution := false