Merge pull request #11183 from romanowski/scala3doc/html-rendering

Migrate away from dokka: Part 1

Author: romanowski

scala3doc/resources/dotty_res/images/dotty-logo-white.svg renamed to docs/images/dotty-logo-white.svg

@@ -1544,19 +1544,13 @@ object Build {
       def joinProducts(products: Seq[java.io.File]): String =
         products.iterator.map(_.getAbsolutePath.toString).mkString(" ")
 
-      val dokkaVersion = "1.4.10.2"
       val flexmarkVersion = "0.42.12"
 
       project.settings(commonBootstrappedSettings).
         dependsOn(`scala3-compiler-bootstrapped`).
         dependsOn(`scala3-tasty-inspector`).
         settings(
-          // Needed to download dokka and its dependencies
-          resolvers += Resolver.jcenterRepo,
           libraryDependencies ++= Seq(
-            "org.jetbrains.dokka" % "dokka-core" % dokkaVersion,
-            "org.jetbrains.dokka" % "dokka-base" % dokkaVersion,
-            "org.jetbrains.kotlinx" % "kotlinx-html-jvm" % "0.7.2", // Needs update when dokka version changes
             "com.vladsch.flexmark" % "flexmark" % flexmarkVersion,
             "com.vladsch.flexmark" % "flexmark-html-parser" % flexmarkVersion,
             "com.vladsch.flexmark" % "flexmark-ext-anchorlink" % flexmarkVersion,
@@ -1569,18 +1563,14 @@ object Build {
             "com.vladsch.flexmark" % "flexmark-ext-yaml-front-matter" % flexmarkVersion,
             "nl.big-o" % "liqp" % "0.6.7",
             "org.jsoup" % "jsoup" % "1.13.1", // Needed to process .html files for static site
-            "args4j" % "args4j" % "2.33",
             Dependencies.`jackson-dataformat-yaml`,
 
-            "org.jetbrains.dokka" % "dokka-test-api" % dokkaVersion % "test",
             "com.novocode" % "junit-interface" % "0.11" % "test",
           ),
           Test / test := (Test / test).dependsOn(compile.in(Compile).in(`scala3doc-testcases`)).value,
           testcasesOutputDir.in(Test) := joinProducts((`scala3doc-testcases`/Compile/products).value),
           testcasesSourceRoot.in(Test) := (baseDirectory.in(`scala3doc-testcases`).value / "src").getAbsolutePath.toString,
           Compile / mainClass := Some("dotty.dokka.Main"),
-          // There is a bug in dokka that prevents parallel tests withing the same jvm
-          fork.in(test) := true,
           baseDirectory.in(run) := baseDirectory.in(ThisBuild).value,
           generateSelfDocumentation := Def.taskDyn {
             generateDocumentation(
@@ -1665,8 +1655,6 @@ object Build {
           BuildInfoPlugin.buildInfoScopedSettings(Test),
           BuildInfoPlugin.buildInfoScopedSettings(Compile),
           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"
         )
     }
 

project/Build.scala

@@ -4,10 +4,10 @@ import scala.scalajs.js
 
 @js.native
 trait PageEntryJS extends js.Object {
-  val name: String = js.native
-  val description: String = js.native
-  val location: String = js.native
-  val searchKeys: js.Array[String] = js.native
+  val n: String = js.native
+  val t: String = js.native
+  val d: String = js.native
+  val l: String = js.native
 }
 
 case class PageEntry(
@@ -23,10 +23,10 @@ object PageEntry {
     s.headOption.map(firstLetter => firstLetter.toString ++ s.tail.filter(_.isUpper))
 
   def apply(jsObj: PageEntryJS): PageEntry = PageEntry(
-    jsObj.name,
-    jsObj.description,
-    jsObj.location,
-    jsObj.searchKeys.head.toLowerCase,
-    createAcronym(jsObj.searchKeys.head)
+    jsObj.t,
+    jsObj.d,
+    jsObj.l,
+    jsObj.n.toLowerCase,
+    createAcronym(jsObj.n)
   )
 }

scala3doc-js/src/searchbar/PageEntry.scala

@@ -2,8 +2,8 @@ package dotty.dokka
 
 import math.Ordering.Implicits.seqOrdering
 
-class SearchbarEngine(pages: List[PageEntry]) {
-  def query(query: List[Matchers]): List[PageEntry] = {
+class SearchbarEngine(pages: List[PageEntry]):
+  def query(query: List[Matchers]): List[PageEntry] =
     pages
       .map( page =>
         page -> query.map(matcher => matcher(page))
@@ -17,5 +17,3 @@ class SearchbarEngine(pages: List[PageEntry]) {
       .map {
         case (page, matchResults) => page
       }
-  }
-}

scala3doc-js/src/searchbar/engine/SearchbarEngine.scala

@@ -0,0 +1,80 @@
+package tests
+
+package commonlinks:
+  class SomeOtherPackage:
+    def method = 123
+
+  object SomeOtherPackage
+
+  enum SomeOtherEnum:
+    case A
+    case B
+
+
+
+package wikilinks:
+  class SomeClass:
+    def method = 123
+
+  /**
+   * [[AnNonExisitingObject]]
+   * [[SomeClass!.ala]]
+   * @syntax wiki
+   */
+  class BrokenLinks
+
+  /**
+   * [[tests.commonlinks.SomeOtherPackage]]
+   * @syntax wiki
+   */
+  class OtherPackageLink
+
+  /**
+   * [[tests.commonlinks.SomeOtherPackage!method]]
+   * [[tests.commonlinks.SomeOtherEnum!A]]
+   * @syntax wiki
+   */
+  class OtherPackageMembers
+  /**
+   * [[SomeClass]]
+   * @syntax wiki
+   */
+  class SamePackageLink
+
+  /**
+   * [[SomeClass.method]]
+   * @syntax wiki
+   */
+  class SamePackageMembers
+
+// It should be exact copy of wikilinks
+package mdlinks:
+  class SomeClass:
+    def method = 123
+
+  /**
+   * [[AnNonExisitingObject]]
+   * [[SomeClass!.ala]]
+   */
+  class BrokenLinks
+
+  /**
+   * [[tests.commonlinks.SomeOtherPackage]]
+   */
+  class OtherPackageLink
+
+  /**
+   * [[tests.commonlinks.SomeOtherPackage!method]]
+   * [[tests.commonlinks.SomeOtherEnum!A]]
+   * @syntax wiki
+   */
+  class OtherPackageMembers
+  /**
+   * [[SomeClass]]
+   */
+  class SamePackageLink
+
+  /**
+   * [[SomeClass.method]]
+   */
+  class SamePackageMembers

scala3doc-testcases/src/tests/docString.scala

@@ -0,0 +1,52 @@
+package tests.site
+
+
+package some.other:
+  class SomeOtherPackage
+
+class SomeClass:
+  def method(a: Int): Int
+    = 123 + a
+  val field =
+    123
+
+/**
+ * Broken link, that should result a warning not break compilation
+ * [[tests.links.AnObject]]
+
+ */
+class BrokenLink:
+  def verifyIfLinksTestIsGenerated(b: Int): Int
+    = 123
+
+/**
+ * [[tests.links.some.other.SomeOtherPackage]]
+ */
+class OtherPackageLink
+
+/**
+ * [[tests.links.SomeClass]]
+ */
+class SamePackageLink
+
+
+/**
+ * Broken link, that should result a warning not break compilation
+ * [[tests.links.AnObject]]
+
+ */
+class BrokenLinkWiki:
+  def verifyIfLinksTestIsGenerated(b: Int): Int
+    = 123
+
+/**
+ * [[tests.links.some.other.SomeOtherPackage]]
+ *  @syntax wiki
+ */
+class OtherPackageLinkWiki
+
+/**
+ * [[tests.links.SomeClass]]
+ *  @syntax wiki
+ */
+class SamePackageLinkWiki

scala3doc-testcases/src/tests/site.scala

@@ -2,8 +2,7 @@
 
 Scala3doc (name subject to change) is the documentation tool for
 [Dotty](https://github.com/lampepfl/dotty), which is scheduled to become
-Scala 3. It's based on [Dokka](https://github.com/Kotlin/dokka), the
-documentation tool for Kotlin. It uses the TastyInspector to access definitions,
+Scala 3.  It uses the TastyInspector to access definitions,
 which is an officially supported way to access Dotty's perspective of a
 codebase.
 
@@ -48,9 +47,7 @@ CLI command for running our tool is in form: `sbt main -n <name> -o <output> -t
 - `<classpath>`: classpath that was used to generate tasty files
 - `<sources>`: links to source files of module that are used to link symbols on pages to their source file. They need to be supplied in form:
   `local_dir=remote_dir#line_suffix` e.g. `src/main/scala=https://github.com/lampepfl/scala3doc/tree/master/src/main/scala#L`
-- `<documentation>`: directory of static documentation that you would like to render with API documentation. This feature is provided by dokka-site plugin:
-  - [GitHub](https://github.com/VirtusLab/dokka-site)
-  - [Documentation](https://virtuslab.github.io/dokka-site/index.html)
+- `<documentation>`: directory of static documentation that you would like to render with API documentation.
 
 ## Developing
 
@@ -164,16 +161,6 @@ Make sure all the tests pass (simply run `sbt test` to verify that).
 
 ## FAQ
 
-### Why depend on Dokka?
-
-We have two primary reasons for depending on Dokka. One of them is division of
-labour - Dokka already has a team of maintainers, and it supports an excellent
-API which already allowed us to quite easily generate documentation with it. By
-depending on Dokka, we will be able to share a large portion of the maintenance
-burden. The second reason is very pragmatic - on our own, it'd be difficult for
-us to reach even feature parity with Scaladoc, simply because of workforce
-constraints. Meanwhile, Dokka maintainers from VirtusLab reached out to us with
-an offer of help, which we were happy to take.
 
 ### Why use TASTy?
 

scala3doc/README.md

@@ -0,0 +1,24 @@
+package dotty.dokka
+
+import java.nio.file.Path
+
+val staticFileSymbolUUID = "___staticFile___"
+
+val topLevelDri = DRI("/")
+
+// we may need target...
+final case class DRI(
+  location: String,
+  anchor: String = "",
+  origin: String = "",
+  symbolUUID: String = ""
+):
+  def withNoOrigin = copy(origin = "")
+
+  def isStaticFile = symbolUUID == staticFileSymbolUUID
+
+  def asFileLocation: String = location.replace(".","/")
+
+object DRI:
+  def forPath(path: Path) =
+    DRI(location = path.toString, symbolUUID = staticFileSymbolUUID)