Merge pull request #15132 from lampepfl/language-reference-backport

Backport changes from stable documentation branch

Author: julienrf

.github/workflows/language-reference.yaml

@@ -21,7 +21,6 @@ jobs:
         uses: actions/checkout@v3
         with:
           path: 'dotty'
-          ref: 'language-reference-stable'
           fetch-depth: 0
           ssh-key: ${{ secrets.DOCS_KEY }}
 

docs/_docs/reference/other-new-features/other-new-types.md renamed to docs/_docs/reference/other-new-features/other-new-features.md

@@ -69,7 +69,7 @@ subsection:
           - page: reference/metaprogramming/reflection.md
           - page: reference/metaprogramming/tasty-inspect.md
       - title: Other New Features
-        index: reference/other-new-features/other-new-types.md
+        index: reference/other-new-features/other-new-features.md
         subsection:
           - page: reference/other-new-features/trait-parameters.md
           - page: reference/other-new-features/transparent-traits.md

docs/sidebar.yml

@@ -1381,21 +1381,33 @@ object Build {
         generateDocumentation(Testcases)
       }.value,
 
+      // Generate the Scala 3 reference documentation (published at https://docs.scala-lang.org/scala3/reference)
       generateReferenceDocumentation := Def.inputTaskDyn {
         val shouldRegenerateExpectedLinks = (Space ~> literal("--no-regenerate-expected-links")).?.parsed.isEmpty
 
         generateStaticAssetsTask.value
 
+        // Move all the source files to a temporary directory and apply some changes specific to the reference documentation
         val temp = IO.createTemporaryDirectory
         IO.copyDirectory(file("docs"), temp / "docs")
         IO.delete(temp / "docs" / "_blog")
 
+        // Overwrite the main layout and the sidebar
         IO.copyDirectory(
           file("project") / "resources" / "referenceReplacements",
           temp / "docs",
           overwrite = true
         )
 
+        // Add redirections from previously supported URLs, for some pages
+        for (name <- Seq("changed-features", "contextual", "dropped-features", "metaprogramming", "other-new-features")) {
+          val path = temp / "docs" / "_docs" / "reference" / name / s"${name}.md"
+          val contentLines = IO.read(path).linesIterator.to[collection.mutable.ArrayBuffer]
+          contentLines.insert(1, s"redirectFrom: /${name}.html") // Add redirection
+          val newContent = contentLines.mkString("\n")
+          IO.write(path, newContent)
+        }
+
         val languageReferenceConfig = Def.task {
           Scala3.value
             .add(OutputDir("scaladoc/output/reference"))
@@ -1404,7 +1416,7 @@ object Build {
             .add(ProjectVersion("3.1.2")) // TODO: Change that later to the current version tag. (This must happen on first forward this branch to stable release tag)
             .remove[VersionsDictionaryUrl]
             .add(SourceLinks(List(
-              dottySrcLink(referenceVersion, temp.getAbsolutePath + "=")
+              dottySrcLink("language-reference-stable", temp.getAbsolutePath + "=")
             )))
             .withTargets(List("___fake___.scala"))
         }

project/Build.scala

@@ -49,7 +49,7 @@ subsection:
       - page: reference/metaprogramming/reflection.md
       - page: reference/metaprogramming/tasty-inspect.md
   - title: Other New Features
-    index: reference/other-new-features/other-new-types.md
+    index: reference/other-new-features/other-new-features.md
     subsection:
       - page: reference/other-new-features/trait-parameters.md
       - page: reference/other-new-features/transparent-traits.md

project/resources/referenceReplacements/sidebar.yml

@@ -9,7 +9,7 @@ EXPECTED_LINKS_FILE=$2 # The location of expected-links.txt is passed as a secon
 
 pushd $DOCS_DIR > /dev/null # Go to docs dir but remember previous location
 # We need to go to docs dir to make find return correct relative paths
-find . -type f -name "*.html" | sort | (popd > /dev/null; diff $EXPECTED_LINKS_FILE -;)
+find . -type f -name "*.html" | LC_ALL=C sort | (popd > /dev/null; diff $EXPECTED_LINKS_FILE -;)
 # We list every html file in documentation, then sort it and finally compare to the expected links list.
 # Before running diff we need to popd to return to the previous location because we don't have relative path to the expected links file.
 

project/scripts/docsLinksStability

@@ -1,3 +1,4 @@
+./changed-features.html
 ./changed-features/compiler-plugins.html
 ./changed-features/eta-expansion-spec.html
 ./changed-features/eta-expansion.html
@@ -20,6 +21,7 @@
 ./changed-features/type-inference.html
 ./changed-features/vararg-splices.html
 ./changed-features/wildcards.html
+./contextual.html
 ./contextual/by-name-context-parameters.html
 ./contextual/context-bounds.html
 ./contextual/context-functions-spec.html
@@ -38,6 +40,7 @@
 ./contextual/using-clauses.html
 ./docs/reference/other-new-features/named-typeargs.html
 ./docsScalaLangResources/scaladoc-assets.html
+./dropped-features.html
 ./dropped-features/auto-apply.html
 ./dropped-features/class-shadowing-spec.html
 ./dropped-features/class-shadowing.html
@@ -78,6 +81,7 @@
 ./language-versions/binary-compatibility.html
 ./language-versions/index.html
 ./language-versions/source-compatibility.html
+./metaprogramming.html
 ./metaprogramming/compiletime-ops.html
 ./metaprogramming/index.html
 ./metaprogramming/inline.html
@@ -97,6 +101,7 @@
 ./new-types/type-lambdas.html
 ./new-types/union-types-spec.html
 ./new-types/union-types.html
+./other-new-features.html
 ./other-new-features/control-syntax.html
 ./other-new-features/creator-applications.html
 ./other-new-features/experimental-defs.html

project/scripts/expected-links/reference-expected-links.txt

@@ -9,7 +9,7 @@ EXPECTED_LINKS_FILE=$2 # The location of expected-links.txt is passed as a secon
 
 pushd $DOCS_DIR > /dev/null # Go to docs dir but remember previous location
 # We need to go to docs dir to make find return correct relative paths
-find . -type f -name "*.html" | (popd > /dev/null; sort > $2;)
+find . -type f -name "*.html" | (popd > /dev/null; LC_ALL=C sort > $2;)
 # We list every html file in documentation, then sort it and finally write it to the expected links list file.
 # Before writing we need to popd to return to the previous location because we don't have relative path to the expected links file.
 

project/scripts/regenerateExpectedLinks

@@ -103,5 +103,5 @@ case class DocContext(args: Scaladoc.Args, compilerContext: CompilerContext):
       report.warning(
         s"""Following generated file paths might not be compatible with Jekyll:
           |${jekyllIncompatLinks.mkString("\n")}
-          |If using GitHub Pages consider adding a \".nojekyll\" file.
-        """.stripMargin)(using compilerContext)
+          |If using GitHub Pages consider adding a \".nojekyll\" file.""".stripMargin
+      )(using compilerContext)

scaladoc/src/dotty/tools/scaladoc/DocContext.scala

@@ -4,10 +4,12 @@ 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 && 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)
-    )
+    val paths = Option.when(path.isAbsolute && path.startsWith(projectRoot))(projectRoot.relativize(path)).toSeq :+ path
+    paths.iterator.to(LazyList).flatMap { path =>
+      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)
+      )
+    }.headOption
 
 trait ArgParser[T]:
   def parse(s: String): Either[String, T]