Add file path escaping to Scaladoc

As Jekyll (and in extension GitHub pages) makes starting a file/folder
name with a couple characters illegal, those character are now being
replaced with a "$charname" format.
To avoid having $underlinedocs, $underlineblog in url by default, those
default static site directories are stripped of the underline character.
Some tests concerning links were adjusted to accomodate the changes.
Example testcase for illegal jekyll chars in Scaladoc was also added.

Author: jchyb

scaladoc-testcases/src/_docs/tests/Adoc.scala renamed to scaladoc-testcases/src/docs/tests/Adoc.scala

@@ -1,4 +1,4 @@
-package _docs.tests
+package docs.tests
 
 class Adoc:
   def foo = 123

scaladoc-testcases/src/example/JekyllEscapes.scala

@@ -0,0 +1,5 @@
+package example
+
+package jekyllEscapes:
+  object #~
+  object ~>~

scaladoc/src/dotty/tools/scaladoc/renderers/Locations.scala

@@ -47,8 +47,9 @@ trait Locations(using ctx: DocContext):
               case "<empty>" :: tail => "_empty_" :: tail
               case other => other
             if ctx.args.apiSubdirectory then "api" :: fqn else fqn
-        cache.put(dri, path)
-        path
+        val escapedPath = escapePath(path)
+        cache.put(dri, escapedPath)
+        escapedPath
       case cached => cached
 
   private def unknownPage(dri: DRI): String =

scaladoc/src/dotty/tools/scaladoc/renderers/Renderer.scala

@@ -101,7 +101,7 @@ abstract class Renderer(rootPackage: Member, val members: Map[DRI, Member], prot
     val all = navigablePage +: redirectPages
     // We need to check for conflicts only if we have top-level member called docs
     val hasPotentialConflict =
-      rootPackage.members.exists(m => m.name.startsWith("_docs"))
+      rootPackage.members.exists(m => m.name.startsWith("docs"))
 
     if hasPotentialConflict then
       def walk(page: Page): Unit =

scaladoc/src/dotty/tools/scaladoc/site/StaticSiteContext.scala

@@ -23,7 +23,15 @@ class StaticSiteContext(
   val docsPath = root.toPath.resolve("_docs")
   val blogPath = root.toPath.resolve("_blog")
 
-  val relativizeFrom = if args.apiSubdirectory then docsPath else root.toPath
+  def relativizeAndStrip(path: Path): Path = 
+    if args.apiSubdirectory then 
+      docsPath.relativize(path)
+    else 
+      val relativised = root.toPath.relativize(path).toString()
+      // we remove all the '_' from _docs, _blog ... as having
+      // $underlinedocs in the url by default will look quite ugly
+      val withUnderlineRemoved = relativised.replaceFirst("^\\_", "")
+      Paths.get(withUnderlineRemoved)
 
   val siteExtensions = Set(".html", ".md")
 
@@ -91,7 +99,7 @@ class StaticSiteContext(
     }
 
   def driFor(dest: Path): DRI =
-    val rawFilePath = relativizeFrom.relativize(dest)
+    val rawFilePath = relativizeAndStrip(dest)
     val pageName = dest.getFileName.toString
     val dotIndex = pageName.lastIndexOf('.')
 

scaladoc/src/dotty/tools/scaladoc/tasty/SymOps.scala

@@ -259,7 +259,7 @@ class SymOpsWithLinkCache:
         else
           (sym.className, sym.anchor)
 
-        val location = (sym.packageNameSplitted ++ className).map(escapeFilename(_))
+        val location = (sym.packageNameSplitted ++ className).map(filename => if filename != ".." then escapeFilename(filename) else filename)
 
         val externalLink = {
             import reflect._

scaladoc/src/dotty/tools/scaladoc/util/escape.scala

@@ -9,3 +9,19 @@ object Escape:
       .replace("/", "$div")
       .replace("\\", "$bslash")
     if escaped != filename then escaped + "$" else escaped
+
+  def escapePath(path: Seq[String]) = path.escapeIllegalJekyllChars
+
+  /**  
+   *  Jekyll (also used by GitHub Pages) by default makes a couple characters 
+   *  illegal to use in file name beginnings. Those can be disabled manually,
+   *  however as suggested by #14612 and like supported in Scala 2 scaladoc
+   *  it's better to have those characters escaped here by default.
+   */
+  extension (path: Seq[String]) private def escapeIllegalJekyllChars: Seq[String] =
+    path.map(
+      _.replaceAll("^~", "\\$tilde")
+        .replaceAll("^\\_", "\\$underline")
+        .replaceAll("^\\.", "\\$dot")
+        .replaceAll("^\\#", "\\$hash")
+    )

scaladoc/test/dotty/tools/scaladoc/ReportingTest.scala

@@ -76,11 +76,11 @@ class ReportingTest:
     val docsRoot = testDocPath.resolve("conflicts-pages").toString
     checkReportedDiagnostics(_.copy(
       docsRoot = Some(docsRoot),
-      tastyFiles = tastyFiles("tests", rootPck = "_docs")
+      tastyFiles = tastyFiles("tests", rootPck = "docs")
     )){ diag =>
       assertNoWarning(diag)
       val Seq(msg) = diag.errorMsgs.map(_.toLowerCase)
-      Seq("conflict","api", "static", "page", "_docs/tests/adoc.html")
+      Seq("conflict","api", "static", "page", "docs/tests/adoc.html")
       .foreach( word =>
           Assert.assertTrue(s"Error message: $msg should contains $word", msg.contains(word))
         )

scaladoc/test/dotty/tools/scaladoc/renderers/LocationTests.scala

@@ -44,8 +44,8 @@ class LocationTests:
       locations.escapedAbsolutePathWithAnchor(new DRI(location, anchor))
 
     assertEquals(
-      "scala/%23::.html#abcde",
-      pathWithAnchor("scala.#::", "abcde")
+      "scala/$hash%23::.html#abcde",
+      pathWithAnchor("scala.##::", "abcde")
     )
 
     assertEquals(

scaladoc/test/dotty/tools/scaladoc/site/NavigationTest.scala

@@ -44,5 +44,5 @@ class NavigationTest extends BaseHtmlTest:
       )),
     ))
 
-    testNavMenu("_docs/Adoc.html", topLevelNav)
+    testNavMenu("docs/Adoc.html", topLevelNav)
   }

scaladoc/test/dotty/tools/scaladoc/site/SiteGeneratationTest.scala

@@ -32,13 +32,13 @@ class SiteGeneratationTest extends BaseHtmlTest:
       }
 
   def testDocPages()(using ProjectContext) =
-    checkFile("_docs/Adoc.html")(title = "Adoc", header = "Header in Adoc", parents = Seq(projectName))
-    checkFile("_docs/dir/index.html")(title = "A directory", header = "A directory", parents = Seq(projectName))
-    checkFile("_docs/dir/nested.html")(
+    checkFile("docs/Adoc.html")(title = "Adoc", header = "Header in Adoc", parents = Seq(projectName))
+    checkFile("docs/dir/index.html")(title = "A directory", header = "A directory", parents = Seq(projectName))
+    checkFile("docs/dir/nested.html")(
       title = "Nested in a directory", header = "Nested in a directory", parents = Seq(projectName, "A directory"))
 
   def testDocIndexPage()(using ProjectContext) =
-    checkFile("_docs/index.html")(title = projectName, header = s"$projectName in header")
+    checkFile("docs/index.html")(title = projectName, header = s"$projectName in header")
 
   def testApiPages(
     mainTitle: String = "API",
@@ -66,13 +66,13 @@ class SiteGeneratationTest extends BaseHtmlTest:
     testDocIndexPage()
     testApiPages()
 
-    withHtmlFile("_docs/Adoc.html"){ content  =>
+    withHtmlFile("docs/Adoc.html"){ content  =>
         content.assertAttr("p a","href", "../tests/site/SomeClass.html")
     }
 
     withHtmlFile("tests/site/SomeClass.html"){ content  =>
       content.assertAttr(".breadcrumbs a","href",
-        "../../_docs/index.html", "../../index.html", "../site.html", "SomeClass.html"
+        "../../docs/index.html", "../../index.html", "../site.html", "SomeClass.html"
       )
     }
   }
@@ -98,7 +98,7 @@ class SiteGeneratationTest extends BaseHtmlTest:
   @Test
   def staticLinking() = withGeneratedSite(testDocPath.resolve("static-links")){
 
-    withHtmlFile("_docs/Adoc.html"){ content  =>
+    withHtmlFile("docs/Adoc.html"){ content  =>
         content.assertAttr("p a","href",
         "dir/html.html",
         "dir/name...with..dots..html",