Merge pull request #13587 from BarkingBad/scaladoc/move-docs

Add script for docs preprocessing for static site
scala · Sep 30, 2021 · 01c70a2 · 01c70a2
2 parents 6b721b6 + deaa6c1
commit 01c70a2
Show file tree

Hide file tree

Showing 136 changed files with 1,285 additions and 826 deletions.
diff --git a/.gitignore b/.gitignore
@@ -102,3 +102,6 @@ cs
 
 # Coursier test product
 compiler/test-coursier/run/*.jar
+
+# Docs
+docs-for-dotty-page/*
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,4 @@
+This directory is for keeping all the compiler related docs.
+
+For serving this files, one should notice that files under `docs/docs/reference` and `docs/docs/usage/scaladoc` are designed to be compatible with `docs.scala-lang` jekyll page.
+Preprocessing the sources to be compatible with scaladoc static site is done via script at `project/CopyDocs.scala`
diff --git a/docs/docs/reference/changed-features.md b/docs/docs/reference/changed-features.md
@@ -0,0 +1,9 @@
+---
+title: "Other Changed Features"
+type: chapter
+num: 51
+previous-page: /scala3/reference/other-new-features/type-test
+next-page: /scala3/reference/changed-features/numeric-literals
+---
+
+The following pages document the features that have changed in Scala 3, compared to Scala 2.
diff --git a/docs/docs/reference/changed-features/compiler-plugins.md b/docs/docs/reference/changed-features/compiler-plugins.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Changes in Compiler Plugins"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/compiler-plugins.html
+type: section
+num: 67
+previous-page: /scala3/reference/changed-features/eta-expansion
+next-page: /scala3/reference/changed-features/lazy-vals-init
 ---
 
 Compiler plugins are supported by Dotty (and Scala 3) since 0.9. There are two notable changes

diff --git a/docs/docs/reference/changed-features/eta-expansion-spec.md b/docs/docs/reference/changed-features/eta-expansion-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Automatic Eta Expansion - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/eta-expansion-spec.html
 ---
 
 ## Motivation

diff --git a/docs/docs/reference/changed-features/eta-expansion.md b/docs/docs/reference/changed-features/eta-expansion.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Automatic Eta Expansion"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/eta-expansion.html
+type: section
+num: 66
+previous-page: /scala3/reference/changed-features/pattern-matching
+next-page: /scala3/reference/changed-features/compiler-plugins
 ---
 
 The conversion of _methods_ into _functions_ has been improved and happens automatically for methods with one or more parameters.
@@ -36,7 +38,7 @@ rather than `next _`.
 The reason for excluding nullary methods from automatic eta expansion
 is that Scala implicitly inserts the `()` argument, which would
 conflict with eta expansion. Automatic `()` insertion is
-[limited](../dropped-features/auto-apply.md) in Scala 3, but the fundamental ambiguity
+[limited](../dropped-features/auto-apply.html) in Scala 3, but the fundamental ambiguity
 remains.
 
-[More details](eta-expansion-spec.md)
+[More details](eta-expansion-spec.html)
diff --git a/docs/docs/reference/changed-features/implicit-conversions-spec.md b/docs/docs/reference/changed-features/implicit-conversions-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Implicit Conversions - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-conversions-spec.html
 ---
 
 ## Implementation
@@ -82,7 +82,7 @@ implicit val myConverter: Int => String = _.toString
 implicit val myConverter: Conversion[Int, String] = _.toString
 ```
 
-Note that implicit conversions are also affected by the [changes to implicit resolution](implicit-resolution.md) between Scala 2 and Scala 3.
+Note that implicit conversions are also affected by the [changes to implicit resolution](implicit-resolution.html) between Scala 2 and Scala 3.
 
 ## Motivation for the changes
 
@@ -109,9 +109,9 @@ will report a type error, because `Map` isn't an instance of
 Implicit values that are used as views should see their type changed to `Conversion`.
 
 For the migration of implicit conversions that are affected by the
-changes to implicit resolution, refer to the [Changes in Implicit Resolution](implicit-resolution.md) for more information.
+changes to implicit resolution, refer to the [Changes in Implicit Resolution](implicit-resolution.html) for more information.
 
 ## Reference
 
-For more information about implicit resolution, see [Changes in Implicit Resolution](implicit-resolution.md).
+For more information about implicit resolution, see [Changes in Implicit Resolution](implicit-resolution.html).
 Other details are available in [PR #2065](https://github.com/lampepfl/dotty/pull/2065).
diff --git a/docs/docs/reference/changed-features/implicit-conversions.md b/docs/docs/reference/changed-features/implicit-conversions.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Implicit Conversions"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-conversions.html
+type: section
+num: 60
+previous-page: /scala3/reference/changed-features/implicit-resolution
+next-page: /scala3/reference/changed-features/overload-resolution
 ---
 
 An _implicit conversion_, also called _view_, is a conversion that
@@ -61,4 +63,4 @@ implicitly[Ordering[A]] // Ok, will use the implicit conversion from
                         // `A` to `Int` and the `Ordering` for `Int`.
 ```
 
-[More details](implicit-conversions-spec.md)
+[More details](implicit-conversions-spec.html)
diff --git a/docs/docs/reference/changed-features/implicit-resolution.md b/docs/docs/reference/changed-features/implicit-resolution.md
@@ -1,8 +1,11 @@
 ---
-layout: doc-page
 title: "Changes in Implicit Resolution"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/implicit-resolution.html
+type: section
+num: 59
+previous-page: /scala3/reference/changed-features/type-inference
+next-page: /scala3/reference/changed-features/implicit-conversions
 ---
+
 This section describes changes to the implicit resolution that apply both to the new `given`s and to the old-style `implicit`s in Scala 3.
 Implicit resolution uses a new algorithm which caches implicit results
 more aggressively for performance. There are also some changes that

diff --git a/docs/docs/reference/changed-features/imports.md b/docs/docs/reference/changed-features/imports.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Imports"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/imports.html
+type: section
+num: 56
+previous-page: /scala3/reference/changed-features/wildcards
+next-page: /scala3/reference/changed-features/type-checking
 ---
 
 The syntax of wildcard and renaming imports (and exports) has changed.

diff --git a/docs/docs/reference/changed-features/interpolation-escapes.md b/docs/docs/reference/changed-features/interpolation-escapes.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Escapes in interpolations"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/interpolation-escapes.html
 ---
 
 In Scala 2 there is no straightforward way to represent a single quote character `"` in a single quoted interpolation. A `\` character can't be used for that because interpolators themselves decide how to handle escaping, so the parser doesn't know whether the `"` should be escaped or used as a terminator.

diff --git a/docs/docs/reference/changed-features/lazy-vals-init.md b/docs/docs/reference/changed-features/lazy-vals-init.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
-title: Lazy Vals initialization
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/lazy-vals-init.html
+title: Lazy Vals Initialization
+type: section
+num: 68
+previous-page: /scala3/reference/changed-features/compiler-plugins
+next-page: /scala3/reference/changed-features/main-functions
 ---
 
 Scala 3 implements [Version 6](https://docs.scala-lang.org/sips/improved-lazy-val-initialization.html#version-6---no-synchronization-on-this-and-concurrent-initialization-of-fields)

diff --git a/docs/docs/reference/changed-features/main-functions.md b/docs/docs/reference/changed-features/main-functions.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Main Methods"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/main-functions.html
+type: section
+num: 69
+previous-page: /scala3/reference/changed-features/lazy-vals-init
+next-page: /scala3/reference/dropped-features
 ---
 
 Scala 3 offers a new way to define programs that can be invoked from the command line:
@@ -57,7 +59,7 @@ The Scala compiler generates a program from a `@main` method `f` as follows:
  - The class has a static method `main` with the usual signature. It takes an `Array[String]`
    as argument and returns `Unit`.
  - The generated `main` method calls method `f` with arguments converted using
-   methods in the [`scala.util.CommandLineParser`](https://dotty.epfl.ch/api/scala/util/CommandLineParser$.html) object.
+   methods in the [`scala.util.CommandLineParser`](https://scala-lang.org/api/3.x/scala/util/CommandLineParser$.html) object.
 
 For instance, the `happyBirthDay` method above would generate additional code equivalent to the following class:
 
@@ -85,5 +87,5 @@ object happyBirthday extends App:
   ...
 ```
 
-The previous functionality of `App`, which relied on the "magic" [`DelayedInit`](../dropped-features/delayed-init.md) trait, is no longer available. [`App`](https://dotty.epfl.ch/api/scala/App.html) still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build
+The previous functionality of `App`, which relied on the "magic" [`DelayedInit`]({% link _scala3-reference/dropped-features/delayed-init.md %}) trait, is no longer available. [`App`](https://scala-lang.org/api/3.x/scala/App.html) still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build
 between Scala 2 and Scala 3, it is recommended to use an explicit `main` method with an `Array[String]` argument instead.
diff --git a/docs/docs/reference/changed-features/match-syntax.md b/docs/docs/reference/changed-features/match-syntax.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Match Expressions"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/match-syntax.html
+type: section
+num: 62
+previous-page: /scala3/reference/changed-features/overload-resolution
+next-page: /scala3/reference/changed-features/vararg-splices
 ---
 
 The syntactical precedence of match expressions has been changed.
@@ -47,7 +49,7 @@ The syntactical precedence of match expressions has been changed.
 
 The new syntax of match expressions is as follows.
 
-```ebnf
+```
 InfixExpr    ::=  ...
                |  InfixExpr MatchClause
 SimpleExpr   ::=  ...

diff --git a/docs/docs/reference/changed-features/numeric-literals.md b/docs/docs/reference/changed-features/numeric-literals.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Numeric Literals"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/numeric-literals.html
+type: section
+num: 52
+previous-page: /scala3/reference/changed-features
+next-page: /scala3/reference/changed-features/structural-types
 ---
 
 [Document was moved](../experimental/numeric-literals.md)
diff --git a/docs/docs/reference/changed-features/operators.md b/docs/docs/reference/changed-features/operators.md
@@ -1,13 +1,15 @@
 ---
-layout: doc-page
 title: "Rules for Operators"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/operators.html
+type: section
+num: 54
+previous-page: /scala3/reference/changed-features/structural-types
+next-page: /scala3/reference/changed-features/wildcards
 ---
 
 The rules for infix operators have changed in some parts:
 
 First, an alphanumeric method can be used as an infix operator only if its definition carries an `infix` modifier. Second, it is recommended (but not enforced) to
-augment definitions of symbolic operators with [`@targetName` annotations](../other-new-features/targetName.md). Finally,
+augment definitions of symbolic operators with [`@targetName` annotations](../other-new-features/targetName.html). Finally,
 a syntax change allows infix operators to be written on the left in a multi-line expression.
 
 ## The `infix` Modifier
@@ -97,7 +99,7 @@ or if the `-source future` option is given in Dotty/Scala 3.
 
 ## The `@targetName` Annotation
 
-It is recommended that definitions of symbolic operators carry a [`@targetName` annotation](../other-new-features/targetName.md) that provides an encoding of the operator with an alphanumeric name. This has several benefits:
+It is recommended that definitions of symbolic operators carry a [`@targetName` annotation](../other-new-features/targetName.html) that provides an encoding of the operator with an alphanumeric name. This has several benefits:
 
  - It helps interoperability between Scala and other languages. One can call
    a Scala-defined symbolic operator from another language using its target name,

diff --git a/docs/docs/reference/changed-features/overload-resolution.md b/docs/docs/reference/changed-features/overload-resolution.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Changes in Overload Resolution"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/overload-resolution.html
+type: section
+num: 61
+previous-page: /scala3/reference/changed-features/implicit-conversions
+next-page: /scala3/reference/changed-features/match-syntax
 ---
 
 Overload resolution in Scala 3 improves on Scala 2 in two ways.
@@ -42,7 +44,7 @@ resolution yields several competing alternatives when `n >= 1` parameter lists a
 into account, then resolution re-tried using `n + 1` argument lists.
 
 This change is motivated by the new language feature
-[extension methods](../contextual/extension-methods.md), where emerges the need to do
+[extension methods](../contextual/extension-methods.html), where emerges the need to do
 overload resolution based on additional argument blocks.
 
 ## Parameter Types of Function Values

diff --git a/docs/docs/reference/changed-features/pattern-bindings.md b/docs/docs/reference/changed-features/pattern-bindings.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Pattern Bindings"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/pattern-bindings.html
+type: section
+num: 64
+previous-page: /scala3/reference/changed-features/vararg-splices
+next-page: /scala3/reference/changed-features/pattern-matching
 ---
 
 In Scala 2, pattern bindings in `val` definitions and `for` expressions are

diff --git a/docs/docs/reference/changed-features/pattern-matching.md b/docs/docs/reference/changed-features/pattern-matching.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Option-less pattern matching"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/pattern-matching.html
+type: section
+num: 65
+previous-page: /scala3/reference/changed-features/pattern-bindings
+next-page: /scala3/reference/changed-features/eta-expansion
 ---
 
 The implementation of pattern matching in Scala 3 was greatly simplified compared to Scala 2. From a user perspective, this means that Scala 3 generated patterns are a *lot* easier to debug, as variables all show up in debug modes and positions are correctly preserved.
@@ -241,4 +243,4 @@ Abstract type testing with `ClassTag` is replaced with `TypeTest` or the alias `
 - pattern `_: X` for an abstract type requires a `TypeTest` in scope
 - pattern `x @ X()` for an unapply that takes an abstract type requires a `TypeTest` in scope
 
-[More details on `TypeTest`](../other-new-features/type-test.md)
+[More details on `TypeTest`](../other-new-features/type-test.html)
diff --git a/docs/docs/reference/changed-features/structural-types-spec.md b/docs/docs/reference/changed-features/structural-types-spec.md
@@ -1,7 +1,7 @@
 ---
-layout: doc-page
+layout: singlepage-overview
+scala3: true
 title: "Programmatic Structural Types - More Details"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/structural-types-spec.html
 ---
 
 ## Syntax
@@ -81,7 +81,7 @@ and `Rs` are structural refinement declarations, and given `v.a` of type `U`, we
 
 Note that `v`'s static type does not necessarily have to conform to `Selectable`, nor does it need to have `selectDynamic` and `applyDynamic` as members. It suffices that there is an implicit
 conversion that can turn `v` into a `Selectable`, and the selection methods could also be available as
-[extension methods](../contextual/extension-methods.md).
+[extension methods](../contextual/extension-methods.html).
 
 ## Limitations of Structural Types
 

diff --git a/docs/docs/reference/changed-features/structural-types.md b/docs/docs/reference/changed-features/structural-types.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Programmatic Structural Types"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/structural-types.html
+type: section
+num: 53
+previous-page: /scala3/reference/changed-features/numeric-literals
+next-page: /scala3/reference/changed-features/operators
 ---
 
 ## Motivation
@@ -189,4 +191,4 @@ differences.
   `java.lang.Class` arguments indicating the method's formal parameter types.
   `Dynamic` comes with `updateDynamic`.
 
-[More details](structural-types-spec.md)
+[More details](structural-types-spec.html)
diff --git a/docs/docs/reference/changed-features/type-checking.md b/docs/docs/reference/changed-features/type-checking.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Changes in Type Checking"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/type-checking.html
+type: section
+num: 57
+previous-page: /scala3/reference/changed-features/imports
+next-page: /scala3/reference/changed-features/type-inference
 ---
 
 *** **TO BE FILLED IN** ***
diff --git a/docs/docs/reference/changed-features/type-inference.md b/docs/docs/reference/changed-features/type-inference.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Changes in Type Inference"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/type-inference.html
+type: section
+num: 58
+previous-page: /scala3/reference/changed-features/type-checking
+next-page: /scala3/reference/changed-features/implicit-resolution
 ---
 
 For more information, see the two presentations

diff --git a/docs/docs/reference/changed-features/vararg-splices.md b/docs/docs/reference/changed-features/vararg-splices.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: "Vararg Splices"
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/vararg-splices.html
+type: section
+num: 63
+previous-page: /scala3/reference/changed-features/match-syntax
+next-page: /scala3/reference/changed-features/pattern-bindings
 ---
 
 The syntax of vararg splices in patterns and function arguments has changed. The new syntax uses a postfix `*`,  analogously to how a vararg parameter is declared.
@@ -24,7 +26,7 @@ The old syntax for splice arguments will be phased out.
 
 ## Syntax
 
-```ebnf
+```
 ArgumentPatterns  ::=  ‘(’ [Patterns] ‘)’
                     |  ‘(’ [Patterns ‘,’] Pattern2 ‘*’ ‘)’
 

diff --git a/docs/docs/reference/changed-features/wildcards.md b/docs/docs/reference/changed-features/wildcards.md
@@ -1,7 +1,9 @@
 ---
-layout: doc-page
 title: Wildcard Arguments in Types
-movedTo: https://docs.scala-lang.org/scala3/reference/changed-features/wildcards.html
+type: section
+num: 55
+previous-page: /scala3/reference/changed-features/operators
+next-page: /scala3/reference/changed-features/imports
 ---
 
 The syntax of wildcard arguments in types has changed from `_` to `?`. Example: