Add indexes to reference chapters

.github/workflows/ci.yaml

@@ -473,7 +473,8 @@ jobs:
       DOTTY_WEBSITE_BOT_TOKEN: ${{ secrets.BOT_TOKEN }}  # If you need to change this:
                                           # Generate one at https://github.com/settings/tokens
                                           # Make sure you have the write permissions to the repo: https://github.com/lampepfl/dotty-website
-      DOCS_SCALALANG_BOT_TOKEN: ${{ secrets.DOCS_SCALALANG_BOT_TOKEN }}  # If you need to change this:
+      # Currently unused token, no need to deploy anything to docs.scala-lang
+      # DOCS_SCALALANG_BOT_TOKEN: ${{ secrets.DOCS_SCALALANG_BOT_TOKEN }}  # If you need to change this:
                                           # Generate one at https://github.com/settings/tokens
                                           # Make sure you have the write permissions to the repo: https://github.com/scala/docs.scala-lang
 

.gitignore

@@ -102,3 +102,7 @@ cs
 
 # Coursier test product
 compiler/test-coursier/run/*.jar
+
+# docs related
+contributors.js
+content-contributors.css

docs/docs/reference/contextual.md → docs/docs/reference/contextual/contextual.md

@@ -50,25 +50,25 @@ Existing Scala programmers by and large have gotten used to the status quo and s
 
 The following pages introduce a redesign of contextual abstractions in Scala. They introduce four fundamental changes:
 
-1. [Given Instances](./contextual/givens.md) are a new way to define basic terms that can be synthesized.  They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.
+1. [Given Instances](./givens.md) are a new way to define basic terms that can be synthesized.  They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.
 
-2. [Using Clauses](./contextual/using-clauses.md) are a new syntax for implicit _parameters_ and their _arguments_. It unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several `using` clauses in a definition.
+2. [Using Clauses](./using-clauses.md) are a new syntax for implicit _parameters_ and their _arguments_. It unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several `using` clauses in a definition.
 
-3. ["Given" Imports](./contextual/given-imports.md) are a new class of import selectors that specifically import
+3. ["Given" Imports](./given-imports.md) are a new class of import selectors that specifically import
    givens and nothing else.
 
-4. [Implicit Conversions](./contextual/conversions.md) are now expressed as given instances of a standard `Conversion` class. All other forms of implicit conversions will be phased out.
+4. [Implicit Conversions](./conversions.md) are now expressed as given instances of a standard `Conversion` class. All other forms of implicit conversions will be phased out.
 
 This section also contains pages describing other language features that are related to context abstraction. These are:
 
-- [Context Bounds](./contextual/context-bounds.md), which carry over unchanged.
-- [Extension Methods](./contextual/extension-methods.md) replace implicit classes in a way that integrates better with type classes.
-- [Implementing Type Classes](./contextual/type-classes.md) demonstrates how some common type classes can be implemented using the new constructs.
-- [Type Class Derivation](./contextual/derivation.md) introduces constructs to automatically derive type class instances for ADTs.
-- [Multiversal Equality](./contextual/multiversal-equality.md) introduces a special type class to support type safe equality.
-- [Context Functions](./contextual/context-functions.md) provide a way to abstract over context parameters.
-- [By-Name Context Parameters](./contextual/by-name-context-parameters.md) are an essential tool to define recursive synthesized values without looping.
-- [Relationship with Scala 2 Implicits](./contextual/relationship-implicits.md) discusses the relationship between old-style implicits and new-style givens and how to migrate from one to the other.
+- [Context Bounds](./context-bounds.md), which carry over unchanged.
+- [Extension Methods](./extension-methods.md) replace implicit classes in a way that integrates better with type classes.
+- [Implementing Type Classes](./type-classes.md) demonstrates how some common type classes can be implemented using the new constructs.
+- [Type Class Derivation](./derivation.md) introduces constructs to automatically derive type class instances for ADTs.
+- [Multiversal Equality](./multiversal-equality.md) introduces a special type class to support type safe equality.
+- [Context Functions](./context-functions.md) provide a way to abstract over context parameters.
+- [By-Name Context Parameters](./by-name-context-parameters.md) are an essential tool to define recursive synthesized values without looping.
+- [Relationship with Scala 2 Implicits](./relationship-implicits.md) discusses the relationship between old-style implicits and new-style givens and how to migrate from one to the other.
 
 Overall, the new design achieves a better separation of term inference from the rest of the language: There is a single way to define givens instead of a multitude of forms all taking an `implicit` modifier. There is a single way to introduce implicit parameters and arguments instead of conflating implicit with normal arguments. There is a separate way to import givens that does not allow them to hide in a sea of normal imports. And there is a single way to define an implicit conversion which is clearly marked as such and does not require special syntax.
 

docs/docs/reference/contextual/derivation-macro.md

@@ -109,7 +109,7 @@ and an age of type `Int`, the equality check we want to generate is the followin
 
 ## Calling the derived method inside the macro
 
-Following the rules in [Macros](../metaprogramming.md) we create two methods.
+Following the rules in [Macros](../metaprogramming/metaprogramming.md) we create two methods.
 One that hosts the top-level splice `eqv` and one that is the implementation.
 Alternatively and what is shown below is that we can call the `eqv` method
 directly. The `eqGen` can trigger the derivation.

docs/docs/reference/metaprogramming.md → docs/docs/reference/metaprogramming/metaprogramming.md

@@ -7,7 +7,7 @@ movedTo: https://docs.scala-lang.org/scala3/reference/metaprogramming.html
 The following pages introduce the redesign of metaprogramming in Scala. They
 introduce the following fundamental facilities:
 
-1. [`inline`](./metaprogramming/inline.md) is a new modifier that guarantees that
+1. [`inline`](./inline.md) is a new modifier that guarantees that
    a definition will be inlined at the point of use. The primary motivation
    behind inline is to reduce the overhead behind function calls and access to
    values. The expansion will be performed by the Scala compiler during the
@@ -18,30 +18,30 @@ introduce the following fundamental facilities:
    programming), macros (enabling compile-time, generative, metaprogramming) and
    runtime code generation (multi-stage programming).
 
-2. [Compile-time ops](./metaprogramming/compiletime-ops.md) are helper definitions in the
+2. [Compile-time ops](./compiletime-ops.md) are helper definitions in the
    standard library that provide support for compile-time operations over values and types.
 
-3. [Macros](./metaprogramming/macros.md) are built on two well-known fundamental
+3. [Macros](./macros.md) are built on two well-known fundamental
    operations: quotation and splicing.  Quotation converts program code to
    data, specifically, a (tree-like) representation of this code. It is
    expressed as `'{...}` for expressions and as `'[...]` for types. Splicing,
    expressed as `${ ... }`, goes the other way: it converts a program's representation
    to program code. Together with `inline`, these two abstractions allow
    to construct program code programmatically.
 
-4. [Runtime Staging](./metaprogramming/staging.md) Where macros construct code at _compile-time_,
+4. [Runtime Staging](./staging.md) Where macros construct code at _compile-time_,
    staging lets programs construct new code at _runtime_. That way,
    code generation can depend not only on static data but also on data available at runtime. This splits the evaluation of the program in two or more phases or ...
    stages. Consequently, this method of generative programming is called "Multi-Stage Programming". Staging is built on the same foundations as macros. It uses
    quotes and splices, but leaves out `inline`.
 
-5. [Reflection](./metaprogramming/reflection.md) Quotations are a "black-box"
+5. [Reflection](./reflection.md) Quotations are a "black-box"
    representation of code. They can be parameterized and composed using
    splices, but their structure cannot be analyzed from the outside. TASTy
    reflection gives a way to analyze code structure by partly revealing the representation type of a piece of code in a standard API. The representation
    type is a form of typed abstract syntax tree, which gives rise to the `TASTy`
    moniker.
 
-6. [TASTy Inspection](./metaprogramming/tasty-inspect.md) Typed abstract syntax trees are serialized
+6. [TASTy Inspection](./tasty-inspect.md) Typed abstract syntax trees are serialized
    in a custom compressed binary format stored in `.tasty` files. TASTy inspection allows
    to load these files and analyze their content's tree structure.

docs/sidebar.yml

@@ -10,6 +10,7 @@ sidebar:
     subsection:
       - page: docs/reference/overview.md
       - title: New Types
+        index: docs/reference/new-types/new-types.md
         subsection:
           - page: docs/reference/new-types/intersection-types.md
           - page: docs/reference/new-types/union-types.md
@@ -18,13 +19,14 @@ sidebar:
           - page: docs/reference/new-types/dependent-function-types.md
           - page: docs/reference/new-types/polymorphic-function-types.md
       - title: Enums
+        index: docs/reference/enums/enums-index.md
         subsection:
           - page: docs/reference/enums/enums.md
           - page: docs/reference/enums/adts.md
           - page: docs/reference/enums/desugarEnums.md
       - title: Contextual Abstractions
+        index: docs/reference/contextual/contextual.md
         subsection:
-          - page: docs/reference/contextual.md
           - page: docs/reference/contextual/givens.md
           - page: docs/reference/contextual/using-clauses.md
           - page: docs/reference/contextual/context-bounds.md
@@ -38,15 +40,16 @@ sidebar:
           - page: docs/reference/contextual/by-name-context-parameters.md
           - page: docs/reference/contextual/relationship-implicits.md
       - title: Metaprogramming
+        index: docs/reference/metaprogramming/metaprogramming.md
         subsection:
-          - page: docs/reference/metaprogramming.md
           - page: docs/reference/metaprogramming/inline.md
           - page: docs/reference/metaprogramming/compiletime-ops.md
           - page: docs/reference/metaprogramming/macros.md
           - page: docs/reference/metaprogramming/staging.md
           - page: docs/reference/metaprogramming/reflection.md
           - page: docs/reference/metaprogramming/tasty-inspect.md
       - title: Other New Features
+        index: docs/reference/other-new-features/other-new-types.md
         subsection:
           - page: docs/reference/other-new-features/trait-parameters.md
           - page: docs/reference/other-new-features/transparent-traits.md
@@ -66,6 +69,7 @@ sidebar:
           - page: docs/reference/other-new-features/type-test.md
           - page: docs/reference/other-new-features/experimental-defs.md
       - title: Other Changed Features
+        index: docs/reference/changed-features/changed-features.md
         subsection:
           - page: docs/reference/changed-features/numeric-literals.md
           - page: docs/reference/changed-features/structural-types.md
@@ -86,6 +90,7 @@ sidebar:
           - page: docs/reference/changed-features/lazy-vals-init.md
           - page: docs/reference/changed-features/main-functions.md
       - title: Dropped Features
+        index: docs/reference/dropped-features/dropped-features.md
         subsection:
           - page: docs/reference/dropped-features/delayed-init.md
           - page: docs/reference/dropped-features/macros.md

project/Build.scala

@@ -1322,7 +1322,6 @@ object Build {
         name,
         scalaSrcLink(stdLibVersion, srcManaged(dottyNonBootstrappedVersion, "scala") + "="),
         dottySrcLink(referenceVersion, srcManaged(dottyNonBootstrappedVersion, "dotty") + "=", "#library/src"),
-        dottySrcLink(referenceVersion, "docs-for-dotty-page=", "#docs"),
         dottySrcLink(referenceVersion),
         "-Ygenerate-inkuire",
       ) ++ scalacOptionsDocSettings(includeExternalMappings) ++ revision ++ params ++ targets
@@ -1383,7 +1382,6 @@ object Build {
         val dest = file(extraArgs.headOption.getOrElse("scaladoc/output/scala3")).getAbsoluteFile
         val justAPI = extraArgs.drop(1).headOption == Some("--justAPI")
         val majorVersion = (LocalProject("scala3-library-bootstrapped") / scalaBinaryVersion).value
-        CopyDocs.copyDocs() // invoke copying function form `project/CopyDocs.scala`
         val dottyJars: Seq[java.io.File] = Seq(
           (`stdlib-bootstrapped`/Compile/products).value,
           (`scala3-interfaces`/Compile/products).value,
@@ -1414,7 +1412,7 @@ object Build {
               "https://scala-lang.org/api/versions.json",
               "-Ydocument-synthetic-types",
               s"-snippet-compiler:${dottyLibRoot}/scala/quoted=compile,${dottyLibRoot}/scala/compiletime=compile"
-            ) ++ (if (justAPI) Nil else Seq("-siteroot", "docs-for-dotty-page", "-Yapi-subdirectory")), includeExternalMappings = false)
+            ) ++ (if (justAPI) Nil else Seq("-siteroot", "docs", "-Yapi-subdirectory")), includeExternalMappings = false)
 
         if (dottyJars.isEmpty) Def.task { streams.value.log.error("Dotty lib wasn't found") }
         else if (justAPI) generateDocTask

project/DocumentationWebsite.scala

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