Merge pull request #14669 from dotty-staging/scaladoc/tweak-reference-documentation

bishabosha · web-flow · commit 21a5401f0345 · 2022-03-17T11:06:10.000+01:00
Tweak Language Reference documentation
diff --git a/docs/_blog/index.html b/docs/_blog/index.html
@@ -6,7 +6,7 @@
     <h1>{{ page.title }}</h1>
 
     <ul class="post-list">
-        {% for post in site.posts %}
+        {% for post in site.subpages %}
             <li>
                 <h2>
                     <a href="{{ post.url }}">{{ post.title }}</a>
diff --git a/docs/_docs/contributing/index.md b/docs/_docs/contributing/index.md
@@ -0,0 +1,4 @@
+---
+layout: index
+title: Contributing
+---
diff --git a/docs/_docs/index.md b/docs/_docs/index.md
@@ -1,6 +1,6 @@
 ---
-layout: doc-page
-redirectFrom: docs/index.html
+layout: index
+redirectFrom: /docs/index.html
 ---
 
 Dotty is the project name for technologies that are considered for inclusion in Scala 3. Scala has
@@ -16,7 +16,3 @@ be a big step towards realizing the full potential of these ideas. Its main obje
 In this documentation you will find information on how to use the Dotty compiler on your machine,
 navigate through the code, setup Dotty with your favorite IDE and more!
 
-Table of Contents
-=================
-{% assign titles = sidebar.titles %}
-{% include "table-of-contents" %}
diff --git a/docs/_docs/internals/index.md b/docs/_docs/internals/index.md
@@ -0,0 +1,5 @@
+---
+layout: index
+title: Internals
+---
+
diff --git a/docs/_docs/reference/changed-features/changed-features.md b/docs/_docs/reference/changed-features/changed-features.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "Other Changed Features"
 movedTo: https://docs.scala-lang.org/scala3/reference/changed-features.html
 ---
diff --git a/docs/_docs/reference/contextual/contextual.md b/docs/_docs/reference/contextual/contextual.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "Contextual Abstractions"
 movedTo: https://docs.scala-lang.org/scala3/reference/contextual.html
 ---
diff --git a/docs/_docs/reference/dropped-features/dropped-features.md b/docs/_docs/reference/dropped-features/dropped-features.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "Dropped Features"
 movedTo: https://docs.scala-lang.org/scala3/reference/dropped-features.html
 ---
diff --git a/docs/_docs/reference/enums/enums-index.md b/docs/_docs/reference/enums/enums-index.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "Enums"
 movedTo: https://docs.scala-lang.org/scala3/reference/enums.html
 ---
diff --git a/docs/_docs/reference/experimental/named-typeargs.md b/docs/_docs/reference/experimental/named-typeargs.md
@@ -1,7 +1,7 @@
 ---
 layout: doc-page
 title: "Named Type Arguments"
-redirectFrom: reference/other-new-features/named-typeargs.html
+redirectFrom: /docs/reference/other-new-features/named-typeargs.html
 movedTo: https://docs.scala-lang.org/scala3/reference/experimental/named-typeargs.html
 ---
 
diff --git a/docs/_docs/reference/experimental/overview.md b/docs/_docs/reference/experimental/overview.md
@@ -1,7 +1,8 @@
 ---
 layout: doc-page
-title: "Overview"
+title: "Experimental"
 movedTo: https://docs.scala-lang.org/scala3/reference/experimental/overview.html
+redirectFrom: overview.html
 ---
 
 ### Experimental language features
diff --git a/docs/_docs/reference/language-versions/language-versions.md b/docs/_docs/reference/language-versions/language-versions.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "Language Versions"
 ---
 
diff --git a/docs/_docs/reference/metaprogramming/metaprogramming.md b/docs/_docs/reference/metaprogramming/metaprogramming.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "Metaprogramming"
 movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming.html
 ---
diff --git a/docs/_docs/reference/new-types/new-types.md b/docs/_docs/reference/new-types/new-types.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "New Types"
 movedTo: https://docs.scala-lang.org/scala3/reference/new-types.html
 ---
diff --git a/docs/_docs/reference/other-new-features/other-new-types.md b/docs/_docs/reference/other-new-features/other-new-types.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "Other New Features"
 movedTo: https://docs.scala-lang.org/scala3/reference/other-new-features.html
 ---
diff --git a/docs/_docs/reference/overview.md b/docs/_docs/reference/overview.md
@@ -1,7 +1,8 @@
 ---
 layout: doc-page
-title: "Overview"
+title: "Reference"
 movedTo: https://docs.scala-lang.org/scala3/reference/overview.html
+redirectFrom: overview.html
 ---
 
 Scala 3 implements many language changes and improvements over Scala 2.
diff --git a/docs/_docs/usage/dottydoc.md b/docs/_docs/usage/dottydoc.md
@@ -107,7 +107,7 @@ An example of this would be:
 To be rendered as templates, each blog post should have front-matter and a
 `layout` declaration.
 
-The posts are also available in the variable `site.posts` throughout the site.
+The posts are also available in the variable `site.subpages` throughout the site.
 The fields of these objects are the same as in
 `[BlogPost](dotty.tools.dottydoc.staticsite.BlogPost)`.
 
diff --git a/docs/_docs/usage/index.md b/docs/_docs/usage/index.md
@@ -0,0 +1,4 @@
+---
+layout: index
+title: Usage
+---
diff --git a/docs/_docs/usage/scaladoc/index.md b/docs/_docs/usage/scaladoc/index.md
@@ -1,5 +1,5 @@
 ---
-layout: doc-page
+layout: index
 title: "Scaladoc"
 ---
 
diff --git a/docs/_layouts/index.html b/docs/_layouts/index.html
@@ -1,4 +1,15 @@
 ---
-layout: main
+layout: static-site-main
 ---
-<h1>{{ content }}</h1>
+<h1>{{ page.title }}</h1>
+
+{{ content }}
+
+<h2>Table of Contents</h2>
+<ul class="table-of-contents">
+  {% for subpage in site.subpages %}
+      <li>
+          <a href="{{ subpage.url }}">{{ subpage.title }}</a>
+      </li>
+  {% endfor %}
+</ul>
diff --git a/docs/sidebar.yml b/docs/sidebar.yml
@@ -2,6 +2,7 @@ index: index.md
 subsection:
   - title: Usage
     directory: docs/usage
+    index: usage/index.md
     subsection:
       - page: usage/sbt-projects.md
       - page: usage/ide-support.md
@@ -17,8 +18,8 @@ subsection:
           - page: usage/scaladoc/static-site.md
   - title: Reference
     directory: docs/reference
+    index: reference/overview.md
     subsection:
-      - page: reference/overview.md
       - title: New Types
         index: reference/new-types/new-types.md
         subsection:
@@ -137,8 +138,8 @@ subsection:
           - page: reference/dropped-features/wildcard-init.md
       - title: Experimental Features
         directory: experimental
+        index: reference/experimental/overview.md
         subsection:
-          - page: reference/experimental/overview.md
           - page: reference/experimental/canthrow.md
           - page: reference/experimental/erased-defs.md
           - page: reference/experimental/erased-defs-spec.md
@@ -157,6 +158,7 @@ subsection:
       - page: reference/features-classification.md
   - title: Contributing
     directory: docs/contributing
+    index: contributing/index.md
     subsection:
       - page: contributing/contribute-knowledge.md
       - page: contributing/getting-started.md
@@ -175,6 +177,7 @@ subsection:
           - page: contributing/procedures/vulpix.md
   - title: Internals
     directory: docs/internals
+    index: internals/index.md
     subsection:
       - page: internals/backend.md
       - page: internals/classpaths.md
diff --git a/project/Build.scala b/project/Build.scala
@@ -1392,6 +1392,7 @@ object Build {
             .add(OutputDir("scaladoc/output/reference"))
             .add(SiteRoot(s"${temp.getAbsolutePath}/docs"))
             .add(ProjectName("Scala 3 Reference"))
+            .remove[VersionsDictionaryUrl]
             .add(SourceLinks(List(
               dottySrcLink(referenceVersion, temp.getAbsolutePath + "=")
             )))
diff --git a/project/resources/referenceReplacements/sidebar.yml b/project/resources/referenceReplacements/sidebar.yml
@@ -1,6 +1,5 @@
 index: reference/overview.md
 subsection:
-  - page: reference/overview.md
   - title: New Types
     index: reference/new-types/new-types.md
     subsection:
@@ -119,8 +118,8 @@ subsection:
       - page: reference/dropped-features/wildcard-init.md
   - title: Experimental Features
     directory: experimental
+    index: reference/experimental/overview.md
     subsection:
-      - page: reference/experimental/overview.md
       - page: reference/experimental/canthrow.md
       - page: reference/experimental/erased-defs.md
       - page: reference/experimental/erased-defs-spec.md
@@ -136,4 +135,4 @@ 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
+  - page: reference/features-classification.md
diff --git a/scaladoc-js/common/src/code-snippets/CodeSnippets.scala b/scaladoc-js/common/src/code-snippets/CodeSnippets.scala
@@ -179,7 +179,7 @@ class CodeSnippets:
     val buttonsSection = getButtonsSection(snippet)
     buttonsSection.foreach(s =>
       s.appendChild(copyButton)
-      if !snippet.hasAttribute("hasContext") then {
+      if snippet.hasAttribute("runnable") then {
         s.appendChild(toScastieButton)
         s.appendChild(runButton)
         s.appendChild(exitButton)
diff --git a/scaladoc-testcases/docs/_docs/docs/f1.md b/scaladoc-testcases/docs/_docs/docs/f1.md
@@ -1,7 +1,7 @@
 ---
 layout: static-site-main
 redirectFrom:
-  - docs/fr.html
-  - docs/my-custom-link
+  - /docs/fr.html
+  - /docs/my-custom-link
 ---
 F1
diff --git a/scaladoc/src/dotty/tools/scaladoc/site/LoadedTemplate.scala b/scaladoc/src/dotty/tools/scaladoc/site/LoadedTemplate.scala
@@ -39,7 +39,7 @@ case class LoadedTemplate(
       )
 
   def resolveToHtml(ctx: StaticSiteContext): ResolvedPage =
-    val posts = children.map(_.lazyTemplateProperties(ctx))
+    val subpages = children.filterNot(_.hidden).map(_.lazyTemplateProperties(ctx))
     def getMap(key: String) = templateFile.settings.getOrElse(key, Map.empty).asInstanceOf[Map[String, Object]]
 
     val sourceLinks = if !file.exists() then Nil else
@@ -50,7 +50,7 @@ case class LoadedTemplate(
         ctx.sourceLinks.pathTo(actualPath, operation = "edit", optionalRevision = Some("master")).map("editSource" -> _)
 
     val updatedSettings = templateFile.settings ++ ctx.projectWideProperties +
-      ("site" -> (getMap("site") + ("posts" -> posts))) + ("urls" -> sourceLinks.toMap) +
+      ("site" -> (getMap("site") + ("subpages" -> subpages))) + ("urls" -> sourceLinks.toMap) +
       ("page" -> (getMap("page") + ("title" -> templateFile.title.name)))
 
     templateFile.resolveInner(RenderingContext(updatedSettings, ctx.layouts))(using ctx)
diff --git a/scaladoc/src/dotty/tools/scaladoc/site/StaticSiteContext.scala b/scaladoc/src/dotty/tools/scaladoc/site/StaticSiteContext.scala
@@ -46,10 +46,12 @@ class StaticSiteContext(
     allTemplates.flatMap { loadedTemplate =>
       val redirectFrom = loadedTemplate.templateFile.settings.getOrElse("page", Map.empty).asInstanceOf[Map[String, Object]].get("redirectFrom")
       def redirectToTemplate(redirectFrom: String) =
-        val fakeFile = new File(docsPath.toFile, redirectFrom)
-        val driFrom = driFor(fakeFile.toPath)
+        val path = if redirectFrom.startsWith("/")
+          then relativizeFrom.resolve(redirectFrom.drop(1))
+          else loadedTemplate.file.toPath.resolveSibling(redirectFrom)
+        val driFrom = driFor(path)
         val driTo = driFor(loadedTemplate.file.toPath)
-        (LoadedTemplate(layouts("redirect"), List.empty, fakeFile), driFrom, driTo)
+        (LoadedTemplate(layouts("redirect"), List.empty, path.toFile), driFrom, driTo)
       redirectFrom.map {
         case redirectFrom: String => Seq(redirectToTemplate(redirectFrom))
         case redirects: List[?] => redirects.asInstanceOf[List[String]].map(redirectToTemplate)
diff --git a/scaladoc/src/dotty/tools/scaladoc/tasty/comments/markdown/SnippetRenderer.scala b/scaladoc/src/dotty/tools/scaladoc/tasty/comments/markdown/SnippetRenderer.scala
@@ -5,7 +5,6 @@ import com.vladsch.flexmark.html._
 import util.HTML._
 
 import dotty.tools.scaladoc.snippets._
-import dotty.tools.scaladoc.util.HTML._
 
 case class SnippetLine(content: String, lineNo: Int, classes: Set[String] = Set.empty, messages: Seq[String] = Seq.empty, attributes: Map[String, String] = Map.empty):
   def withClass(cls: String) = this.copy(classes = classes + cls)
@@ -134,15 +133,26 @@ object SnippetRenderer:
     div(cls := "snippet-label")(name)
   ).toString
 
-  def renderSnippetWithMessages(snippetName: Option[String], codeLines: Seq[String], messages: Seq[SnippetCompilerMessage], hasContext: Boolean): String =
+  def renderSnippetWithMessages(snippetName: Option[String], codeLines: Seq[String], messages: Seq[SnippetCompilerMessage], hasContext: Boolean, success: Boolean): String =
     val transformedLines = wrapCodeLines.andThen(addCompileMessages(messages)).apply(codeLines).map(_.toHTML)
     val codeHTML = s"""<code class="language-scala">${transformedLines.mkString("")}</code>"""
-    s"""<div class="snippet" scala-snippet ${if hasContext then "hasContext" else ""}><div class="buttons"></div><pre>$codeHTML</pre>${snippetName.fold("")(snippetLabel(_))}</div>"""
+    val isRunnable = !hasContext && success
+    val attrs = Seq(
+      Option.when(isRunnable)(Attr("runnable") := "")
+    ).flatten
+    div(cls := "snippet", Attr("scala-snippet") := "", attrs)(
+      div(cls := "buttons")(),
+      pre(
+        raw(codeHTML)
+      ),
+      raw(snippetName.fold("")(snippetLabel(_)))
+    ).toString
 
   def renderSnippetWithMessages(node: ExtendedFencedCodeBlock): String =
     renderSnippetWithMessages(
       node.name,
       node.codeBlock.getContentChars.toString.split("\n").map(_ + "\n").toSeq,
       node.compilationResult.toSeq.flatMap(_.messages),
-      node.hasContext
+      node.hasContext,
+      node.compilationResult.fold(false)(_.isSuccessful)
     )

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +layout: index
 +title: Contributing
 +---