Sync with the stable documentation branch (#16483)

This pull request is syncing the main with changes from
language-reference-stable.

It was created automatically after
29639f9 by @WojciechMazur

Author: bishabosha

.github/workflows/ci.yaml

@@ -2,8 +2,6 @@ name: Dotty
 
 on:
   push:
-    branches-ignore:
-      - 'language-reference-stable'
     tags:
       - '**'
   pull_request:

docs/_assets/css/frontpage.css

@@ -28,6 +28,7 @@ h1#main {
 /* navigation */
 header {
   font-size: 24px;
+  margin-block-end: calc(2* var(--base-spacing));
 }
 
 header .nav-item i {

docs/_assets/docsScalaLangResources/scaladoc-assets.html

@@ -0,0 +1,4 @@
+---
+layout: index
+title: Procedures
+---

docs/_docs/contributing/procedures/index.md

@@ -0,0 +1,4 @@
+---
+layout: index
+title: IDEs and Tools
+---

docs/_docs/contributing/tools/index.md

@@ -1,4 +1,9 @@
-# GADTs - Broad overview
+---
+layout: doc-page
+title: "GADTs - Broad overview"
+---
+
+## Introduction
 
 There are multiple levels to the implementation. They deal with slightly different problems. The most important levels are the following ones:
 
@@ -18,9 +23,9 @@ There are also other parts to supporting GADTs. Roughly in order of importance,
     1.  Attachment key is named `inferredGadtConstraints`.
 4.  When we select members on a type that may have GADT constraints, we perform special "healing" by approximating the type using those constraints. We cannot take the constraints into account because member lookup is cached, and GADT constraints are only valid for specific scopes.
 
-# Useful widgets
+## Useful widgets
 
-## Expr
+### Expr
 
 This is the classical GADT example:
 
@@ -36,7 +41,7 @@ enum Expr[T] {
 }
 ```
 
-## EQ
+### EQ
 
 The following enum will result in an equality constraint between `S` and `T` if we match on it:
 
@@ -46,7 +51,7 @@ enum EQ[S, T] {
 }
 ```
 
-## SUB
+### SUB
 
 The following enum will result in a subtyping constraint `S <: T` if we match on it:
 
@@ -56,9 +61,9 @@ enum SUB[-S, +T] {
 }
 ```
 
-# Details of above
+## Details of above
 
-## What abstract types can have GADT constraints
+### What abstract types can have GADT constraints
 
 Right now, we record GADT constraints for:
 
@@ -67,9 +72,9 @@ Right now, we record GADT constraints for:
 
 There is a branch on the way which will also record them for type members (so path-dependent types) and singleton types. It has a paper associated: "Implementing path-depepdent GADTs for Scala 3".
 
-## What are necessary relationships? Any examples?
+### What are necessary relationships? Any examples?
 
-### Covariance means no constraint is necessary
+#### Covariance means no constraint is necessary
 
 Standard (non-case) classes allow "strange" inheritance which means that we cannot infer any information from covariant type parameters.
 
@@ -90,7 +95,7 @@ class Weird(list: List[String]) extends IntList with Expr[Nothing]
 
 Case classes have a special check which disallows inheritance like `Weird`. This means we can infer extra information from them.
 
-## Breaking down the constraints
+### Breaking down the constraints
 
 ```scala
 class Expr[A]
@@ -113,9 +118,9 @@ def foo[T](e: Expr[List[T]]): T =
   }
 ```
 
-## Relation betweeen GadtConstraint and OrderingConstraint
+### Relation betweeen GadtConstraint and OrderingConstraint
 
-### Internal and external types
+#### Internal and external types
 
 GadtConstraint uses OrderingConstraint as the datastructure to record information about GADT constraints.
 
@@ -127,9 +132,9 @@ To solve this, GadtConstraint internally creates TypeParamRefs which it adds to
 
 The TypeParamRefs and TypeVars registered in one constraint cannot ever be present in types mentioned in the other type constraint. The internal TypeParamRefs and TypeVars cannot ever leak out of the GadtConstraint. We cannot ever record a bound in GadtConstraint which mentions TypeParamRefs used for type inference. (That part is ensured by the way TypeComparer is organised &#x2013; we will always try to record bounds in the "normal" constraint before recording a GADT bound.)
 
-# Other details
+## Other details
 
-## TypeComparer approximations
+### TypeComparer approximations
 
 TypeComparer sometimes approximates the types it compares. Let's see an example based on these definitions:
 
@@ -142,11 +147,11 @@ when comparing if `IntList <: Expr[Int]`, `TypeComparer` will approximate `IntLi
 
 The variables which TypeComparer sets are `approxState` and `frozenGadt`.
 
-## Necessary/sufficient either
+### Necessary/sufficient either
 
 TypeComparer sometimes needs to approximate some constraints, specifically when dealing with intersection and union types. The way this approximation works changes if we're currently inferring GADT constraints. This is hopefully documented well in TypeComparer in doc comments for `necessaryEither` and `sufficientEither`.
 
-## Types bound in patterns
+### Types bound in patterns
 
 ```scala
 (list : List[Int]) match {
@@ -161,7 +166,7 @@ TypeComparer sometimes needs to approximate some constraints, specifically when
 }
 ```
 
-## Internal structure of OrderingConstraint
+### Internal structure of OrderingConstraint
 
 Imagine we have two type parameters in scope, `A` and `B`.
 
@@ -184,19 +189,19 @@ B <: A
 
 The first two constraints are "entries" &#x2013; they are easy to look up whenever we ask for bounds of `A` or `B`. The third constraint is an ordering &#x2013; it helps with correctly propagating the bounds we record.
 
-# Possible broad improvements
+## Possible broad improvements
 
-## Allow OrderingConstraint to record bounds for things other than TypeParamRefs
+### Allow OrderingConstraint to record bounds for things other than TypeParamRefs
 
 This would mean we no longer need to keep the bidirectional mapping in GadtConstraint.
 
-## Not mixing OrderingConstraint and ConstraintHandling in GadtConstraint
+### Not mixing OrderingConstraint and ConstraintHandling in GadtConstraint
 
 GadtConstraint right now mixes OrderingConstraint and ConstraintHandling. The first one is supposed to be the immutable constraint datastructure. The second one implements mutable functionality around a variable containing the immutable datastructure.
 
 GadtConstraint mixes them both. Things would be better organised if GadtConstraint was split like the normal constraint.
 
-## Creating a separate TypeComparer for breaking down types into GADT constraints
+### Creating a separate TypeComparer for breaking down types into GADT constraints
 
 TypeComparer is biased towards one specific way of approximating constraints. When we infer types, it's ok to be "optimistic". When inferring GADT constraints, we should be as pessimistic as possible, in order to only infer constraints which are necessary.
 

docs/_docs/internals/gadts.md

@@ -284,7 +284,7 @@ Note the following properties of `Mirror` types,
 + The methods `ordinal` and `fromProduct` are defined in terms of `MirroredMonoType` which is the type of kind-`*`
   which is obtained from `MirroredType` by wildcarding its type parameters.
 
-### Implementing `derived` with `Mirror`
+## Implementing `derived` with `Mirror`
 
 As seen before, the signature and implementation of a `derived` method for a type class `TC[_]` are arbitrary, but we expect it to typically be of the following form:
 
@@ -484,7 +484,7 @@ The framework described here enables all three of these approaches without manda
 For a brief discussion on how to use macros to write a type class `derived`
 method please read more at [How to write a type class `derived` method using macros](./derivation-macro.md).
 
-### Syntax
+## Syntax
 
 ```
 Template          ::=  InheritClauses [TemplateBody]

docs/_docs/reference/contextual/derivation.md

@@ -174,6 +174,6 @@ val z = l2(3.1)
 l1.mul(x, y) // type checks
 l1.mul(x, z) // error: found l2.Logarithm, required l1.Logarithm
 ```
-In general, one can think of an opaque type as being only transparent in the scope of `private[this]`.
+In general, one can think of an opaque type as being only transparent in the scope of `private[this]` (unless the type is a top level definition - in this case, it's transparent only within the file it's defined in).
 
 [More details](opaques-details.md)

docs/_docs/reference/other-new-features/opaques.md

@@ -5,9 +5,7 @@
 <main>
   <header>
     {% if urls.editSource %}
-    <a class="text-button with-link body-small" href="{{ urls.editSource }}">
-      Edit this page on GitHub
-    </a>
+    <a class="text-button with-link body-small" href="{{ urls.editSource }}">Edit this page on GitHub</a>
     {% endif %}
     <h1 class="h600">{{ page.title }}</h1>
   </header>

docs/_layouts/doc-page.html

@@ -1,15 +1,24 @@
 ---
 layout: static-site-main
 ---
-<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>
+
+<main>
+  <header>
+    {% if urls.editSource %}
+    <!--<a class="text-button with-link body-small" href="{{ urls.editSource }}">Edit this page on GitHub</a>-->
+    {% endif %}
+    <h1 class="h600">{{ page.title }}</h1>
+  </header>
+
+  {{ content }}
+
+  <h2 class="h500">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>
+
+</main>

docs/_layouts/index.html

@@ -1,9 +1,5 @@
 ---
 layout: base
-extraJS:
-  - js/contributors.js
-extraCSS:
-  - css/content-contributors.css
 ---
 
 <div id="content-wrapper">{{ content }}</div>

docs/_layouts/main.html

@@ -6,10 +6,13 @@
   <div id="site-header"></div>
   {% if page.nightlyOf %}
   <aside class="warning">
+    <div class='icon'></div>
+    <div class='content'>
     This is a nightly documentation. The content of this page may not be
     consistent with the current stable version of language. Click
     <a href="{{ page.nightlyOf }}">here</a> to find the stable version of this
     page.
+    </div>
   </aside>
   {% endif %} {{ content }}
   <div class="divider" />
@@ -28,7 +31,7 @@
     </div>
     {% endif %} {% if page.next %}
     <div>
-      <span class="body-small">Next</span>
+      <span class="body-small arrow-navigation--next">Next</span>
       <a
         rel="next"
         href="{{ page.next.url }}"

docs/_layouts/static-site-main.html

@@ -56,7 +56,6 @@ subsection:
           - page: reference/metaprogramming/macros-spec.md
             hidden: true
           - page: reference/metaprogramming/simple-smp.md # description of a simplified metaprogramming language, this might not be the best place for it
-            hidden: true
           - page: reference/metaprogramming/staging.md
           - page: reference/metaprogramming/reflection.md
           - page: reference/metaprogramming/tasty-inspect.md
@@ -174,11 +173,13 @@ subsection:
       - page: contributing/debugging.md
       - title: IDEs and Tools
         directory: tools
+        index: contributing/tools/index.md
         subsection:
           - page: contributing/tools/ide.md
           - page: contributing/tools/mill.md
           - page: contributing/tools/scalafix.md
       - title: Procedures
+        index: contributing/procedures/index.md
         subsection:
           - page: contributing/procedures/release.md
           - page: contributing/procedures/vulpix.md

docs/sidebar.yml

@@ -14,7 +14,7 @@ object DocumentationWebsite {
 
 
     val contributorsTestcasesDestinationFile = Paths.get("scaladoc-testcases", "docs", "_assets", "js", "contributors.js").toFile
-    val contributorsDestinationFile = Paths.get("docs", "_assets", "js", "contributors.js").toFile
+    val contributorsDestinationFile = baseDest / "dotty_res" / "scripts" / "contributors.js"
     sbt.IO.copyFile(contributorsFile, contributorsTestcasesDestinationFile)
     sbt.IO.copyFile(contributorsFile, contributorsDestinationFile)
 
@@ -25,8 +25,8 @@ object DocumentationWebsite {
     val cssCodeSnippetsSourceFile = cssSourceFileBase / "code-snippets.css"
     sbt.IO.copyFile(cssCodeSnippetsSourceFile, cssCodeSnippetsDesitnationFile)
 
-    val cssContentContributorsTestcasesDesitnationFile = Paths.get("docs", "_assets", "css", "content-contributors.css").toFile
-    val cssContentContributorsDesitnationFile = Paths.get("scaladoc-testcases", "docs", "_assets", "css", "content-contributors.css").toFile
+    val cssContentContributorsTestcasesDesitnationFile = Paths.get("scaladoc-testcases", "docs", "_assets", "css", "content-contributors.css").toFile
+    val cssContentContributorsDesitnationFile = baseDest / "dotty_res" / "styles" / "content-contributors.css"
     val cssContentContributorsSourceFile = cssContentContributorsSourceBaseFile / "content-contributors.css"
     sbt.IO.copyFile(cssContentContributorsSourceFile, cssContentContributorsTestcasesDesitnationFile)
     sbt.IO.copyFile(cssContentContributorsSourceFile, cssContentContributorsDesitnationFile)

project/DocumentationWebsite.scala

@@ -23,15 +23,4 @@
     </div>
     {% endif %}
   </nav>
-  <div class="content-contributors hidden">
-    <h1 class="h200">Contributors to this page</h1>
-    <div id="documentation-contributors" class="contributors-container"></div>
-    {% if urls.editSource %}
-    <div class="github-edit-button">
-      <a class="text-button with-link body-small" href="{{ urls.editSource }}">
-        Edit this page on GitHub
-      </a>
-    </div>
-    {% endif %}
-  </div>
 </div>

project/resources/referenceReplacements/_layouts/static-site-main.html

@@ -2,15 +2,19 @@
 set -eux
 
 echo "Pull request submitted by $AUTHOR";
-signed=$(curl -s https://www.lightbend.com/contribute/cla/scala/check/$AUTHOR | jq -r ".signed");
-if [ "$signed" = "true" ] ; then
+if [ "$AUTHOR" = "github-actions[bot]" ] ; then
   echo "CLA check for $AUTHOR successful";
 else
-  echo "CLA check for $AUTHOR failed";
-  echo "Please sign the Scala CLA to contribute to the Scala compiler.";
-  echo "Go to https://www.lightbend.com/contribute/cla/scala and then";
-  echo "comment on the pull request to ask for a new check.";
-  echo "";
-  echo "Check if CLA is signed: https://www.lightbend.com/contribute/cla/scala/check/$AUTHOR";
-  exit 1;
+  signed=$(curl -s "https://www.lightbend.com/contribute/cla/scala/check/$AUTHOR" | jq -r ".signed");
+  if [ "$signed" = "true" ] ; then
+    echo "CLA check for $AUTHOR successful";
+  else
+    echo "CLA check for $AUTHOR failed";
+    echo "Please sign the Scala CLA to contribute to the Scala compiler.";
+    echo "Go to https://www.lightbend.com/contribute/cla/scala and then";
+    echo "comment on the pull request to ask for a new check.";
+    echo "";
+    echo "Check if CLA is signed: https://www.lightbend.com/contribute/cla/scala/check/$AUTHOR";
+    exit 1;
+  fi;
 fi;

project/scripts/check-cla.sh

@@ -40,7 +40,6 @@
 ./contextual/type-classes.html
 ./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

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

@@ -147,5 +147,7 @@ class CodeSnippets:
     )
   }
 
-  enrichSnippets()
+  window.addEventListener("dynamicPageLoad", (e: Event) => {
+    enrichSnippets()
+  })