Add task generating Scala 3 language reference

scala · Feb 16, 2022 · e92666b · e92666b
1 parent ead669e
commit e92666b
Show file tree

Hide file tree

Showing 5 changed files with 221 additions and 11 deletions.
diff --git a/project/Build.scala b/project/Build.scala
@@ -1256,6 +1256,8 @@ object Build {
   val generateScalaDocumentation = inputKey[Unit]("Generate documentation for dotty lib")
   val generateTestcasesDocumentation  = taskKey[Unit]("Generate documentation for testcases, usefull for debugging tests")
 
+  val generateReferenceDocumentation = taskKey[Unit]("Generate language reference documentation for Scala 3")
+
   lazy val `scaladoc-testcases` = project.in(file("scaladoc-testcases")).
     dependsOn(`scala3-compiler-bootstrapped`).
     settings(commonBootstrappedSettings)
@@ -1378,6 +1380,31 @@ object Build {
         generateDocumentation(Testcases)
       }.value,
 
+      generateReferenceDocumentation := Def.taskDyn {
+        val temp = IO.createTemporaryDirectory
+        IO.copyDirectory(file("docs"), temp / "docs")
+        IO.delete(temp / "docs" / "_blog")
+
+        IO.copyDirectory(
+          file("project") / "resources" / "referenceReplacements",
+          temp / "docs",
+          overwrite = true
+        )
+
+        val languageReferenceConfig = Def.task {
+          Scala3.value
+            .add(OutputDir("scaladoc/output/reference"))
+            .add(SiteRoot(s"${temp.getAbsolutePath}/docs"))
+            .add(ProjectName("Scala 3 Reference"))
+            .add(SourceLinks(List(
+              dottySrcLink(referenceVersion, temp.getAbsolutePath + "=")
+            )))
+            .withTargets(List("___fake___.scala"))
+        }
+
+        generateDocumentation(languageReferenceConfig)
+      }.value,
+
       Test / buildInfoKeys := Seq[BuildInfoKey](
         (Test / Build.testcasesOutputDir),
         (Test / Build.testcasesSourceRoot),
@@ -1763,6 +1790,13 @@ object ScaladocConfigs {
 
   def dottyExternalMapping = ".*scala/.*::scaladoc3::https://dotty.epfl.ch/api/"
   def javaExternalMapping = ".*java/.*::javadoc::https://docs.oracle.com/javase/8/docs/api/"
+  def scalaSrcLink(v: String, s: String) = s"${s}github://scala/scala/v$v#src/library"
+  def dottySrcLink(v: String, sourcesPrefix: String = "", outputPrefix: String = "") =
+    sys.env.get("GITHUB_SHA") match {
+      case Some(sha) =>
+        s"${sourcesPrefix}github://${sys.env("GITHUB_REPOSITORY")}/$sha$outputPrefix"
+      case None => s"${sourcesPrefix}github://lampepfl/dotty/$v$outputPrefix"
+    }
 
   lazy val DefaultGenerationConfig = Def.task {
     def distLocation = (dist / pack).value
@@ -1771,13 +1805,6 @@ object ScaladocConfigs {
     def scalaLib = findArtifactPath(externalCompilerClasspathTask.value, "scala-library")
     def dottyLib = (`scala3-library` / Compile / classDirectory).value
     def srcManaged(v: String, s: String) = s"out/bootstrap/stdlib-bootstrapped/scala-$v/src_managed/main/$s-library-src"
-    def scalaSrcLink(v: String, s: String) = s"${s}github://scala/scala/v$v#src/library"
-    def dottySrcLink(v: String, sourcesPrefix: String = "", outputPrefix: String = "") =
-      sys.env.get("GITHUB_SHA") match {
-        case Some(sha) =>
-          s"${sourcesPrefix}github://${sys.env("GITHUB_REPOSITORY")}/$sha$outputPrefix"
-        case None => s"${sourcesPrefix}github://lampepfl/dotty/$v$outputPrefix"
-      }
 
     def defaultSourceLinks: SourceLinks = SourceLinks(
       List(

diff --git a/project/resources/referenceReplacements/_layouts/static-site-main.html b/project/resources/referenceReplacements/_layouts/static-site-main.html
@@ -0,0 +1,44 @@
+---
+layout: main
+---
+<div class="container">
+  <div id="site-header">
+    <div class="wrap">
+      <nav class="navigation" role="menu">
+        <ul class="navigation-menu">
+          <li class="navigation-menu-item">
+            <a href="https://docs.scala-lang.org/" class="active">Documentation</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://www.scala-lang.org/download/">Download</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://www.scala-lang.org/community/">Community</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://index.scala-lang.org">Libraries</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://www.scala-lang.org/contribute/">Contribute</a>
+          </li>
+          <li class="navigation-menu-item">
+            <a href="https://www.scala-lang.org/blog/">Blog</a>
+          </li>
+        </ul>
+      </nav>
+    </div>
+  </div>
+  {{ content }}
+  <nav class="arrows-wrapper" aria-label="Page navigation">
+    {% if page.previous %}
+    <a rel="prev" href="{{ page.previous }}" class="arrows previous" aria-keyshortcuts="Left">
+        <i class="fa fa-angle-left"></i>
+    </a>
+    {% endif %}
+    {% if page.next %}
+    <a rel="next" href="{{ page.next }}" class="arrows next" aria-keyshortcuts="Right">
+        <i class="fa fa-angle-right"></i>
+    </a>
+    {% endif %}
+  </nav>
+</div>
diff --git a/project/resources/referenceReplacements/sidebar.yml b/project/resources/referenceReplacements/sidebar.yml
@@ -0,0 +1,139 @@
+index: reference/overview.md
+subsection:
+  - page: reference/overview.md
+  - title: New Types
+    index: reference/new-types/new-types.md
+    subsection:
+      - page: reference/new-types/intersection-types.md
+      - page: reference/new-types/intersection-types-spec.md
+      - page: reference/new-types/union-types.md
+      - page: reference/new-types/union-types-spec.md
+      - page: reference/new-types/type-lambdas.md
+      - page: reference/new-types/type-lambdas-spec.md
+      - page: reference/new-types/match-types.md
+      - page: reference/new-types/dependent-function-types.md
+      - page: reference/new-types/dependent-function-types-spec.md
+      - page: reference/new-types/polymorphic-function-types.md
+  - title: Enums
+    index: reference/enums/enums-index.md
+    subsection:
+      - page: reference/enums/enums.md
+      - page: reference/enums/adts.md
+      - page: reference/enums/desugarEnums.md
+  - title: Contextual Abstractions
+    index: reference/contextual/contextual.md
+    directory: contextual
+    subsection:
+      - page: reference/contextual/givens.md
+      - page: reference/contextual/using-clauses.md
+      - page: reference/contextual/context-bounds.md
+      - page: reference/contextual/given-imports.md
+      - page: reference/contextual/extension-methods.md
+      - page: reference/contextual/right-associative-extension-methods.md
+      - page: reference/contextual/type-classes.md
+      - page: reference/contextual/derivation.md
+      - page: reference/contextual/derivation-macro.md
+      - page: reference/contextual/multiversal-equality.md
+      - page: reference/contextual/context-functions.md
+      - page: reference/contextual/context-functions-spec.md
+      - page: reference/contextual/conversions.md
+      - page: reference/contextual/by-name-context-parameters.md
+      - page: reference/contextual/relationship-implicits.md
+  - title: Metaprogramming
+    index: reference/metaprogramming/metaprogramming.md
+    subsection:
+      - page: reference/metaprogramming/inline.md
+      - page: reference/metaprogramming/compiletime-ops.md
+      - page: reference/metaprogramming/macros.md
+      - page: reference/metaprogramming/macros-spec.md
+      - page: reference/metaprogramming/staging.md
+      - page: reference/metaprogramming/reflection.md
+      - page: reference/metaprogramming/tasty-inspect.md
+  - title: Other New Features
+    index: reference/other-new-features/other-new-types.md
+    subsection:
+      - page: reference/other-new-features/trait-parameters.md
+      - page: reference/other-new-features/transparent-traits.md
+      - page: reference/other-new-features/creator-applications.md
+      - page: reference/other-new-features/export.md
+      - page: reference/other-new-features/opaques.md
+      - page: reference/other-new-features/opaques-details.md
+      - page: reference/other-new-features/open-classes.md
+      - page: reference/other-new-features/parameter-untupling.md
+      - page: reference/other-new-features/parameter-untupling-spec.md
+      - page: reference/other-new-features/kind-polymorphism.md
+      - page: reference/other-new-features/matchable.md
+      - page: reference/other-new-features/threadUnsafe-annotation.md
+      - page: reference/other-new-features/targetName.md
+      - page: reference/other-new-features/control-syntax.md
+      - page: reference/other-new-features/indentation.md
+      - page: reference/other-new-features/safe-initialization.md
+      - page: reference/other-new-features/type-test.md
+      - page: reference/other-new-features/experimental-defs.md
+  - title: Other Changed Features
+    directory: changed-features
+    index: reference/changed-features/changed-features.md
+    subsection:
+      - page: reference/changed-features/numeric-literals.md
+      - page: reference/changed-features/structural-types.md
+      - page: reference/changed-features/structural-types-spec.md
+      - page: reference/changed-features/operators.md
+      - page: reference/changed-features/wildcards.md
+      - page: reference/changed-features/imports.md
+      - page: reference/changed-features/type-checking.md
+      - page: reference/changed-features/type-inference.md
+      - page: reference/changed-features/implicit-resolution.md
+      - page: reference/changed-features/implicit-conversions.md
+      - page: reference/changed-features/implicit-conversions-spec.md
+      - page: reference/changed-features/overload-resolution.md
+      - page: reference/changed-features/match-syntax.md
+      - page: reference/changed-features/vararg-splices.md
+      - page: reference/changed-features/pattern-bindings.md
+      - page: reference/changed-features/pattern-matching.md
+      - page: reference/changed-features/eta-expansion.md
+      - page: reference/changed-features/eta-expansion-spec.md
+      - page: reference/changed-features/compiler-plugins.md
+      - page: reference/changed-features/lazy-vals-init.md
+      - page: reference/changed-features/main-functions.md
+  - title: Dropped Features
+    index: reference/dropped-features/dropped-features.md
+    subsection:
+      - page: reference/dropped-features/delayed-init.md
+      - page: reference/dropped-features/macros.md
+      - page: reference/dropped-features/existential-types.md
+      - page: reference/dropped-features/type-projection.md
+      - page: reference/dropped-features/do-while.md
+      - page: reference/dropped-features/procedure-syntax.md
+      - page: reference/dropped-features/package-objects.md
+      - page: reference/dropped-features/early-initializers.md
+      - page: reference/dropped-features/class-shadowing.md
+      - page: reference/dropped-features/class-shadowing-spec.md
+      - page: reference/dropped-features/limit22.md
+      - page: reference/dropped-features/xml.md
+      - page: reference/dropped-features/symlits.md
+      - page: reference/dropped-features/auto-apply.md
+      - page: reference/dropped-features/weak-conformance.md
+      - page: reference/dropped-features/weak-conformance-spec.md
+      - page: reference/dropped-features/nonlocal-returns.md
+      - page: reference/dropped-features/this-qualifier.md
+      - page: reference/dropped-features/wildcard-init.md
+  - title: Experimental Features
+    directory: experimental
+    subsection:
+      - page: reference/experimental/overview.md
+      - page: reference/experimental/canthrow.md
+      - page: reference/experimental/erased-defs.md
+      - page: reference/experimental/erased-defs-spec.md
+      - page: reference/experimental/named-typeargs.md
+      - page: reference/experimental/named-typeargs-spec.md
+      - page: reference/experimental/numeric-literals.md
+      - page: reference/experimental/explicit-nulls.md
+      - page: reference/experimental/cc.md
+  - page: reference/syntax.md
+  - title: Language Versions
+    index: reference/language-versions/language-versions.md
+    subsection:
+      - page: reference/language-versions/source-compatibility.md
+      - page: reference/language-versions/binary-compatibility.md
+  - page: reference/soft-modifier.md
+  - page: reference/features-classification.md
diff --git a/scaladoc/src/dotty/tools/scaladoc/PathBased.scala b/scaladoc/src/dotty/tools/scaladoc/PathBased.scala
@@ -4,9 +4,7 @@ import java.nio.file.{Path, Paths}
 
 case class PathBased[T](entries: List[PathBased.Entry[T]], projectRoot: Path):
   def get(path: Path): Option[PathBased.Result[T]] =
-    if path.isAbsolute then
-      if path.startsWith(projectRoot) then get(projectRoot.relativize(path))
-      else None
+    if path.isAbsolute && path.startsWith(projectRoot) then get(projectRoot.relativize(path))
     else entries.filter(_.path.forall(p => path.startsWith(p))).maxByOption(_.path.map(_.toString.length)).map(entry =>
       PathBased.Result(entry.path.fold(path)(_.relativize(path)), entry.elem)
     )

diff --git a/scaladoc/src/dotty/tools/scaladoc/renderers/Renderer.scala b/scaladoc/src/dotty/tools/scaladoc/renderers/Renderer.scala
@@ -83,7 +83,9 @@ abstract class Renderer(rootPackage: Member, val members: Map[DRI, Member], prot
         then rootPckPage.withTitle(args.name)
         else {
           val newRootPage = templateToPage(newRoot, siteContext)
-          newRootPage.withNewChildren(Seq(rootPckPage.withTitle("API")))
+          newRootPage.withNewChildren(
+            Seq(rootPckPage.withTitle("API")).filter(_ => rootPackage.members.nonEmpty)
+          )
         }
 
   val redirectPages: Seq[Page] = staticSite.fold(Seq.empty)(siteContext => siteContext.redirectTemplates.map {