New scaladoc version

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/_docs/contributing/procedures/index.md

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

docs/_docs/contributing/tools/index.md

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

docs/_docs/internals/backend.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/contexts.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/dotc-scalac.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/gadts.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/syntax-3.1.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.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/reference/changed-features/imports.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/wildcards.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/contextual/by-name-context-parameters.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/context-functions-spec.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.