Fix sbt tests and make error messages more helpul in case of conflicts in docs

Author: romanowski

sbt-test/sbt-dotty/scaladoc/build.sbt

@@ -6,6 +6,6 @@ TaskKey[Unit]("checkScaladocOptions") := {
 }
 
 TaskKey[Unit]("checkHtmlFiles") := {
-  val helloHtml = (Compile / doc / target).value / "api" / "hello.html"
+  val helloHtml = (Compile / doc / target).value / "hello.html"
   assert(helloHtml.exists)
 }

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

@@ -92,7 +92,7 @@ class HtmlRenderer(rootPackage: Member, val members: Map[DRI, Member])(using ctx
         if page.link.dri.isStaticFile then
           val dest = absolutePath(page.link.dri)
           if apiPaths.contains(dest) then
-            report.error(s"Conflict between static page and API member for $dest")
+            report.error(s"Conflict between static page and API member for $dest. $pathsConflictResoultionMsg")
           page.children.foreach(walk)
 
       all.foreach (walk)

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

@@ -25,6 +25,9 @@ trait Locations(using ctx: DocContext):
 
   var cache = new JHashMap[DRI, Seq[String]]()
 
+  private[renderers] def pathsConflictResoultionMsg =
+    "Using `-Ylegacy-api-layout` flag will move all API documentaiton into `api` subdirectory and will fix this conflict."
+
   // TODO verify if location exisits
   def rawLocation(dri: DRI): Seq[String] =
     cache.get(dri) match

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

@@ -172,7 +172,7 @@ trait Resources(using ctx: DocContext) extends Locations, Writer:
 
   def renderResource(resource: Resource): Seq[String] =
     if resource.path.endsWith(".html") && apiPaths.contains(resource.path) then
-      report.error(s"Conflict between resource and API member for ${resource.path}")
+      report.error(s"Conflict between resource and API member for ${resource.path}. $pathsConflictResoultionMsg")
       Nil
     else
       resource match