New scaladoc version (#16310)

PR with new scaladoc version. We want to merge it to language-ref,
because there is already a reference version generated with older
scaladoc that is bugged in some places. It would be best to replace it
fairly quickly.
This version deployed:
https://szymon-rd.github.io/dotty/scala3/index.html

## Major changes (broadly described):
- New search engine and algorithm. It is faster and gives better
results. We also fixed its UI and introduced no results page.
 - Adjustments in articles layout.
- Packages now form a tree instead of a linear structure. The `scala`
package is first and expanded by default. It also behaves differently
now (it doesn't jump in a way that was confusing to the user anymore)
- Removed flickering of the page. It now behaves as it was written with
some framework with virtual DOMs. We made it by intercepting the event
that would make the browser reload the page, and prerendering the page
before replacing it. The navigation is also faster because of it. It
required us to rework some parts of the website.
- New layout of members section and their contents (more concise and
with improved readability).
 - Quick Navigation in API members. ToC are sticky now. 
- Member section filters are now faster and sticky. Added no results
page.
 - Reworked code snippets style and fonts.
 - Removed contributors (see comments)
 - Styled tables in the Docs.
- Fixed flow of releasing ScalaDoc by modyfing the tasks. It should be
now easier to generate the stable docs, and the versions are fixed in
the testcases config.
- A lot of minor changes in styling and structure of both docs and API
sections. We've redesigned the majority of the page and analyzed the
implementation side to side to make it strictly match the designs.
 - Introduced new icons.
- More details pages are now visible (going to change that and make them
not appear under `Next` instead)
## Fixed bugs with:
 - Search overlay not always disappearing when clicked outside.
 - Bad paths in search results.
- Rendering of members filters. The `clear` icon now appears where it
should and with fixed styling. Dropdown fixed as well.
 - Empty pages in docs
 - Rendering, updating and structure of ToC (`In this article`)
 - Missing pointer cursor
 - Article content shifting when no ToC.
 - Collapsing side nav items.
 - Page jumping when going directly to members.
 - Mobile menu not appearing on some resolutions.
 - Member details hiding on interaction with inheritance graph.
 - Missing spaces in search results.
 - Recent searches not working as intended.
- Linking to a section that has its name duplicated in one doc. Now they
get unique id on duplicates.
 - More minor ones.
## Additional fixes TODO (from @julienrf )
- [x] Instead of showing in the sidebar the previously hidden pages,
hide them also from the “Next” buttons
 - [x] Don’t show all the super types of classes in the list view
- [x] In the detailed view, show the super types of classes, but use a
comma instead of with
- [x] Bring back the “This is a nightly documentation. …” banner (with
proper styling)
 - [x] Fix the “Uncaught TypeError”s
 - [x] Make the table of contents (“In this article” box) scrollable
 - [x] Make header names (long package names) scrollable
 - [ ] Bring back the list of contributors (use --ignore-revs-file)

Author: szymon-rd

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

@@ -30,7 +30,7 @@ BCodeIdiomatic     ---------------->        utilities for code generation, e.g.
 
 The `BTypes.scala` class contains the `BType` class and predefined BTypes
 
-### Data Flow ###
+## Data Flow ##
 Compiler creates a `GenBCode` `Phase`, calls `runOn(compilationUnits)`,
 which calls `run(context)`. This:
 
@@ -51,12 +51,12 @@ which calls `run(context)`. This:
   - `GenBCodePipeline.drainQ3` writes byte arrays to disk
 
 
-### Architecture ###
+## Architecture ##
 The architecture of `GenBCode` is the same as in Scalac. It can be partitioned
 into weakly coupled components (called "subsystems" below):
 
 
-#### (a) The queue subsystem ####
+### (a) The queue subsystem ###
 Queues mediate between processors, queues don't know what each processor does.
 
 The first queue contains AST trees for compilation units, the second queue
@@ -70,7 +70,7 @@ serialization to disk.
 
 This subsystem is described in detail in `GenBCode.scala`
 
-#### (b) Bytecode-level types, BType ####
+### (b) Bytecode-level types, BType ###
 The previous bytecode emitter goes to great lengths to reason about
 bytecode-level types in terms of Symbols.
 
@@ -89,7 +89,7 @@ spec (that's why they aren't documented in `GenBCode`, just read the [JVM 8 spec
 
 All things `BType` can be found in `BCodeGlue.scala`
 
-#### (c) Utilities offering a more "high-level" API to bytecode emission ####
+### (c) Utilities offering a more "high-level" API to bytecode emission ###
 Bytecode can be emitted one opcode at a time, but there are recurring patterns
 that call for a simpler API.
 
@@ -100,7 +100,7 @@ of two strategies.
 All these utilities are encapsulated in file `BCodeIdiomatic.scala`. They know
 nothing about the type checker (because, just between us, they don't need to).
 
-#### (d) Mapping between type-checker types and BTypes ####
+### (d) Mapping between type-checker types and BTypes ###
 So that (c) can remain oblivious to what AST trees contain, some bookkeepers
 are needed:
 
@@ -115,7 +115,7 @@ final def exemplar(csym0: Symbol): Tracked = { ... }
 
 Details in `BTypes.scala`
 
-#### (e) More "high-level" utilities for bytecode emission ####
+### (e) More "high-level" utilities for bytecode emission ###
 In the spirit of `BCodeIdiomatic`, utilities are added in `BCodeHelpers` for
 emitting:
 
@@ -125,5 +125,5 @@ emitting:
 - annotations
 
 
-#### (f) Building an ASM ClassNode given an AST TypeDef ####
+### (f) Building an ASM ClassNode given an AST TypeDef ###
 It's done by `PlainClassBuilder`(see `GenBCode.scala`).

docs/_docs/internals/backend.md

@@ -16,7 +16,7 @@ The `Context` contains the state of the compiler, for example
   * `typerState` (for example undetermined type variables)
   * ...
 
-### Contexts in the typer ###
+## Contexts in the typer ##
 The type checker passes contexts through all methods and adapts fields where
 necessary, e.g.
 
@@ -26,7 +26,7 @@ case tree: untpd.Block => typedBlock(desugar.block(tree), pt)(ctx.fresh.withNewS
 
 A number of fields in the context are typer-specific (`mode`, `typerState`).
 
-### In other phases ###
+## In other phases ##
 Other phases need a context for many things, for example to access the
 denotation of a symbols (depends on the period). However they typically don't
 need to modify / extend the context while traversing the AST. For these phases
@@ -36,7 +36,7 @@ all members.
 **Careful**: beware of memory leaks. Don't hold on to contexts in long lived
 objects.
 
-### Using contexts ###
+## Using contexts ##
 Nested contexts should be named `ctx` to enable implicit shadowing:
 
 ```scala

docs/_docs/internals/contexts.md

@@ -6,7 +6,7 @@ title: "Differences between Scalac and Dotty"
 Overview explanation how symbols, named types and denotations hang together:
 [Denotations1]
 
-### Denotation ###
+## Denotation ##
 Comment with a few details: [Denotations2]
 
 A `Denotation` is the result of a name lookup during a given period
@@ -21,7 +21,7 @@ A `Denotation` is the result of a name lookup during a given period
 Denotations of methods have a signature ([Signature1]), which
 uniquely identifies overloaded methods.
 
-#### Denotation vs. SymDenotation ####
+### Denotation vs. SymDenotation ###
 A `SymDenotation` is an extended denotation that has symbol-specific properties
 (that may change over phases)
 * `flags`
@@ -31,7 +31,7 @@ A `SymDenotation` is an extended denotation that has symbol-specific properties
 `SymDenotation` implements lazy types (similar to scalac). The type completer
 assigns the denotation's `info`.
 
-#### Implicit Conversion ####
+### Implicit Conversion ###
 There is an implicit conversion:
 ```scala
 core.Symbols.toDenot(sym: Symbol)(implicit ctx: Context): SymDenotation
@@ -42,7 +42,7 @@ implicit conversion does **not** need to be imported, it is part of the
 implicit scope of the type `Symbol` (check the Scala spec). However, it can
 only be applied if an implicit `Context` is in scope.
 
-### Symbol ###
+## Symbol ##
 * `Symbol` instances have a `SymDenotation`
 * Most symbol properties in the Scala 2 compiler are now in the denotation (in the Scala 3 compiler).
 
@@ -57,7 +57,7 @@ if (sym is Flags.PackageClass)  // Scala 3 (*)
 `(*)` Symbols are implicitly converted to their denotation, see above. Each
 `SymDenotation` has flags that can be queried using the `is` method.
 
-### Flags ###
+## Flags ##
 * Flags are instances of the value class `FlagSet`, which encapsulates a
   `Long`
 * Each flag is either valid for types, terms, or both
@@ -74,7 +74,7 @@ if (sym is Flags.PackageClass)  // Scala 3 (*)
   `ModuleVal` / `ModuleClass` for either of the two.
 * `flags.is(Method | Param)`: true if `flags` has either of the two
 
-### Tree ###
+## Tree ##
 * Trees don't have symbols
   - `tree.symbol` is `tree.denot.symbol`
   - `tree.denot` is `tree.tpe.denot` where the `tpe` is a `NamdedType` (see
@@ -87,7 +87,7 @@ if (sym is Flags.PackageClass)  // Scala 3 (*)
     using `prefix.member(name)`.
 
 
-### Type ###
+## Type ##
  * `MethodType(paramSyms, resultType)` from scalac =>
     `mt @ MethodType(paramNames, paramTypes)`. Result type is `mt.resultType`
 

docs/_docs/internals/dotc-scalac.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

@@ -16,7 +16,7 @@ hexDigit      ::= ‘0’ | … | ‘9’ | ‘A’ | … | ‘F’ | ‘a’ |
 
 Informal descriptions are typeset as `“some comment”`.
 
-### Lexical Syntax
+## Lexical Syntax
 The lexical syntax of Scala is given by the following grammar in EBNF
 form.
 

docs/_docs/internals/syntax-3.1.md

@@ -30,7 +30,7 @@ hexDigit      ::= ‘0’ | … | ‘9’ | ‘A’ | … | ‘F’ | ‘a’ |
 
 Informal descriptions are typeset as `“some comment”`.
 
-### Lexical Syntax
+## Lexical Syntax
 
 The lexical syntax of Scala is given by the following grammar in EBNF
 form.

docs/_docs/internals/syntax.md

@@ -38,13 +38,13 @@ import scala.annotation as ann
 import java as j
 ```
 
-### Migration
+## Migration
 
 To support cross-building, Scala 3.0 supports the old import syntax with `_` for wildcards and `=>` for renamings in addition to the new one. The old syntax
 will be dropped in a future versions. Automatic rewritings from old to new syntax
 are offered under settings `-source 3.1-migration -rewrite`.
 
-### Syntax
+## Syntax
 
 ```
 Import            ::=  ‘import’ ImportExpr {‘,’ ImportExpr}

docs/_docs/reference/changed-features/imports.md

@@ -10,7 +10,7 @@ List[?]
 Map[? <: AnyRef, ? >: Null]
 ```
 
-### Motivation
+## Motivation
 
 We would like to use the underscore syntax `_` to stand for an anonymous type parameter, aligning it with its meaning in
 value parameter lists. So, just as `f(_)` is a shorthand for the lambda `x => f(x)`, in the future `C[_]` will be a shorthand
@@ -21,7 +21,7 @@ In the future, `F[_]` will mean the same thing, no matter where it is used.
 We pick `?` as a replacement syntax for wildcard types, since it aligns with
 [Java's syntax](https://docs.oracle.com/javase/tutorial/java/generics/wildcardGuidelines.html).
 
-### Migration Strategy
+## Migration Strategy
 
 The migration to the new scheme is complicated, in particular since the [kind projector](https://github.com/typelevel/kind-projector)
 compiler plugin still uses the reverse convention, with `?` meaning parameter placeholder instead of wildcard. Fortunately, kind projector has added `*` as an alternative syntax for `?`.

docs/_docs/reference/changed-features/wildcards.md

@@ -59,7 +59,7 @@ val s = summon[Test.Codec[Option[Int]]](
 
 No local given instance was generated because the synthesized argument is not recursive.
 
-### Reference
+## Reference
 
 For more information, see [Issue #1998](https://github.com/lampepfl/dotty/issues/1998)
 and the associated [Scala SIP](https://docs.scala-lang.org/sips/byname-implicits.html).

docs/_docs/reference/contextual/by-name-context-parameters.md

@@ -74,6 +74,6 @@ See the section on Expressiveness from [Simplicitly: foundations and
 applications of implicit function
 types](https://dl.acm.org/citation.cfm?id=3158130).
 
-### Type Checking
+## Type Checking
 
 After desugaring no additional typing rules are required for context function types.