Enhancements to ScalaDoc: New Features Implemented

docs/_docs/internals/scaladoc/index.md

@@ -0,0 +1,241 @@
+---
+layout: doc-page
+title:  Scaladoc
+partof: scaladoc
+overview-name: Scaladoc
+num: 1
+
+---
+
+
+# Custom Template Tags Documentation
+
+
+## 1. Language Picker Tag
+
+The language_picker tag is a custom tag used to render a language selection dropdown on a page. This tag allows users to switch between different language versions of the content. The available languages are determined based on the configuration and the frontmatter of the page.
+
+### Prequisites:
+ - #### Configuration in config.yaml:
+    The available languages must be defined in the `config.yaml` file under the languages section. Each language should have a corresponding code and name.
+    Example:
+    ```yaml
+    languages:
+    -   code: en
+        name: English
+    -   code: ja
+        name: Japanese
+    ```
+ - #### Language Folders in `_docs`:
+    For each language code specified in config.yaml, there should be a corresponding folder in the _docs directory. These folders contain the translated content for each language.
+    Example:
+    ```
+    _docs/
+    ├── en/
+    ├── ja/
+
+    ```
+ - #### Frontmatter in the page:
+    Each page should have a `languages` key in its frontmatter that lists the available languages for that page. This ensures that the language picker dropdown is rendered with the correct options.
+
+    Example:
+    ```yaml
+    ---
+    title: Getting Started
+    languages: ['en', 'ja']
+    ---
+    ```
+
+### Usage:
+
+```html
+<div class="language-picker-container">
+    { % if page.languages % }
+        { % language_picker languages=page.languages % }
+    { % endif %}
+</div>
+```
+
+### Considerations
+
+- Empty Language List: If the languages list in the frontmatter is empty, the language_picker tag will not render anything.
+- Default Language: If the selected language is en, the language code will be removed from the URL, treating it as the default language.
+- Folder Structure: Ensure that the corresponding language folders exist in the _docs directory; otherwise, the language switch will lead to broken links.
+
+
+
+## 1. Include Tag
+
+### Purpose:
+The `{ % include % }` tag is used to include content from other files or templates within your page. This helps in reusing common elements across multiple pages, such as headers, footers, or any other repeated content.
+
+### Usage:
+```html
+{ % include 'filename' variable1='value1' variable2='value2' % }
+```
+
+
+### Example:
+```html
+{ % include 'header.html' title='Welcome to My Website' % }
+```
+
+### How it Works:
+ - File Inclusion: The tag includes the specified file from a predefined folder.
+ - Passing Variables: You can pass variables when including a file, which can be accessed within the included file using the syntax {{ include.variable1 }}.
+ - Accessing Variables: Inside the included file, the passed variables can be accessed like regular variables, allowing dynamic content based on the context of inclusion.
+
+
+
+## 2. Tabs  Block
+
+### Purpose:
+The { % tabs % } block is used to group content into tabs, allowing users to switch between different content sections without reloading the page. This is useful for organizing content that has multiple views, like installation instructions for different platforms.
+
+### Usage:
+```html
+{ % tabs unique-tabs-id class='additional-class' % }
+  { % tab 'Tab 1' for='unique-tabs-id' % }
+    <!-- Content for Tab 1 -->
+  {  % endtab % }
+
+  { % tab 'Tab 2' for='unique-tabs-id' % }
+    <!-- Content for Tab 2 -->
+  { % endtab % }
+
+{ % endtabs % }
+```
+
+### Example:
+
+```html
+{ % tabs install-instructions % }
+  { % tab 'Windows' for='install-instructions' % }
+
+  { % endtab % }
+
+  { % tab 'macOS' for='install-instructions' % }
+
+  { % endtab % }
+
+{ % endtabs % }
+```
+
+How it Works:
+- Tabs Block: The { % tabs % } tag creates a container for multiple tabs.
+- Tab Content: Each { % tab %  } tag defines the content of a single tab. The for attribute must match the id specified in the { % tabs % } block to correctly link the tab content.
+- Default Tab: You can specify a default tab by using the defaultTab keyword in the { % tab % } tag.
+- Styling: You can apply additional CSS classes to the tabs by specifying the class attribute
+
+
+## 2. AltDetails  Block
+
+### Purpose:
+The { % altDetails % } tag is used to create switchable sections, often referred to as tabs. This is useful for including optional or advanced information that doesn’t need to be visible by default.
+
+### Usage:
+
+```html
+{ % altDetails 'unique-id' 'Title of the Section' % }
+  <!-- Content inside the dropdown -->
+{ % endaltDetails %}
+
+```
+
+### How it Works:
+
+- Collapsible Section: The { % altDetails % } tag creates a section that can be expanded or collapsed by the user.
+- Title and ID: The first argument is a unique identifier for the section, and the second argument is the title displayed when the section is collapsed.
+- Content: Any content placed within the { % altDetails % } and { % endaltDetails % } tags is hidden by default and can be revealed by clicking on the title.
+
+
+# `_data` Folder
+
+The _data folder in your project is used to store YAML, JSON, or CSV files that contain structured data. These files can then be accessed throughout your site using the site.data variable. This is particularly useful for storing site-wide information, such as navigation menus, reusable content blocks, or any other structured data that needs to be referenced across multiple pages.
+
+### Structure and Access
+ - Folder Location: The _data folder should be located in the root directory of your project.
+
+ - File Formats: The _data folder supports .yml, .yaml, .json, and .csv file formats. Each file represents a collection of data that can be accessed using the site.data variable.
+
+ - Accessing Data:
+    - The data within a YAML file can be accessed using `site.data.<file_name>.<key>.`
+    - Replace `<file_name>` with the name of the file (without the extension), and `<key>` with the specific key within the file.
+
+### Example
+
+Suppose you have a YAML file `_data/navigation.yml` with the following content:
+
+```yaml
+main_menu:
+  - name: Home
+    url: /
+  - name: About
+    url: /about/
+  - name: Contact
+    url: /contact/
+```
+
+You can access the data in this file using the following syntax:
+
+```html
+<ul>
+  { % for item in site.data.navigation.main_menu % }
+    <li><a href="{ { item.url } }">{ { item.name } }</a></li>
+  { % endfor % }
+</ul>
+```
+
+### Considerations
+ - File Naming: Make sure the file names are unique to avoid conflicts when accessing data.
+ - Data Structure: Keep the data structure consistent across different files to avoid confusion when accessing data in your templates.
+
+<aside class="info">
+<div class='icon'></div>
+<div class='content'>
+It is preferred to avoid using hyphens in naming conventions. When using LIQP tags, hyphens can be misinterpreted as minus signs, leading to unexpected errors.
+<br/>
+{ { site.data.example['key-with-hyphen'] } }
+
+</div>
+</aside>
+
+
+
+
+
+# Configuration File
+
+The `_config.yaml` file is a central configuration file located in the root directory of your project. It is used to define site-wide settings and variables that can be accessed throughout your site using the `site` variable.
+
+### Structure and Access
+
+- File Location: The _config.yaml file should be placed in the root directory of your project.
+
+- YAML Structure: The file uses YAML syntax to define configuration options. You can define any key-value pairs in this file, and they will be accessible via the site.config.`<key>` variable in your templates.
+
+- Accessing Configuration:
+    - Any configuration setting defined in _config.yaml can be accessed using site.`<key>`.
+    - For example, if you define a key title: My Website, you can access it using site.title.
+
+### Example
+If your _config.yaml includes:
+```yaml
+site_name: My Awesome Site
+description: A description of my awesome site.
+```
+You can access these values in your templates:
+```html
+{ { site.config.site_name } }  <!-- Outputs: My Awesome Site -->
+```
+
+
+
+<aside class="info">
+<div class='icon'></div>
+<div class='content'>
+It is preferred to avoid using hyphens in naming conventions. When using LIQP tags, hyphens can be misinterpreted as minus signs, leading to unexpected errors.
+<br/>
+{ { site.data.example['key-with-hyphen'] } }
+</div>
+</aside>

project/Build.scala

@@ -1776,7 +1776,7 @@ object Build {
         bundleCSS.taskValue
       ),
       libraryDependencies ++= Dependencies.flexmarkDeps ++ Seq(
-        "nl.big-o" % "liqp" % "0.8.2",
+        "nl.big-o" % "liqp" % "0.9",
         "org.jsoup" % "jsoup" % "1.17.2", // Needed to process .html files for static site
         Dependencies.`jackson-dataformat-yaml`,
 

project/Dependencies.scala

@@ -28,5 +28,8 @@ object Dependencies {
     "com.vladsch.flexmark" % "flexmark-ext-yaml-front-matter" % flexmarkVersion,
   )
 
+  private val snakeYamlVersion = "2.2"
+  val `snakeyaml` = "org.yaml" % "snakeyaml" % snakeYamlVersion
+
   val compilerInterface = "org.scala-sbt" % "compiler-interface" % "1.9.6"
 }

project/ScaladocGeneration.scala

@@ -12,8 +12,9 @@ object ScaladocGeneration {
     def serialize: String =
       value match {
         case s: String => s"$key ${escape(s)}"
-        case true => s"$key"
-        case list: List[_] => s"$key:${list.map(x => escape(x.toString)).mkString(",")}"
+        case true      => s"$key"
+        case list: List[_] =>
+          s"$key:${list.map(x => escape(x.toString)).mkString(",")}"
         case _ =>
           println(s"Unsupported setting: $key -> $value")
           ""
@@ -141,10 +142,14 @@ object ScaladocGeneration {
     def key: String = "-dynamic-side-menu"
   }
 
+  case class ExperimentalFeatures(value: Boolean) extends Arg[Boolean] {
+    def key: String = "-experimental-features"
+  }
+
   import _root_.scala.reflect._
 
   trait GenerationConfig {
-    def get[T <: Arg[_] : ClassTag]: Option[T]
+    def get[T <: Arg[_]: ClassTag]: Option[T]
     def add[T <: Arg[_]](arg: T): GenerationConfig
     def remove[T <: Arg[_]: ClassTag]: GenerationConfig
     def withTargets(targets: Seq[String]): GenerationConfig
@@ -154,43 +159,50 @@ object ScaladocGeneration {
 
   object GenerationConfig {
     def apply(): GenerationConfig = GenerationConfigImpl(Seq.empty, Seq.empty)
-    def apply(targets: List[String], args: Arg[_]*): GenerationConfig = args.foldLeft(GenerationConfig()) { (config, elem) =>
-      config.add(elem)
-    }
-    private case class GenerationConfigImpl(targets: Seq[String], args: Seq[Arg[_]]) extends GenerationConfig {
+    def apply(targets: List[String], args: Arg[_]*): GenerationConfig =
+      args.foldLeft(GenerationConfig()) { (config, elem) =>
+        config.add(elem)
+      }
+    private case class GenerationConfigImpl(
+        targets: Seq[String],
+        args: Seq[Arg[_]]
+    ) extends GenerationConfig {
       override def add[T <: Arg[_]](arg: T): GenerationConfig = {
         implicit val tag: ClassTag[T] = ClassTag(arg.getClass)
         val (removedElem, argsWithoutElem) = argsWithout[T](tag)
-        removedElem.foreach(elem => println(s"$elem has been overwritten by $arg"))
+        removedElem.foreach(elem =>
+          println(s"$elem has been overwritten by $arg")
+        )
         GenerationConfigImpl(targets, argsWithoutElem :+ arg)
       }
-      override def remove[T <: Arg[_] : ClassTag]: GenerationConfig = {
+      override def remove[T <: Arg[_]: ClassTag]: GenerationConfig = {
         GenerationConfigImpl(targets, argsWithout[T]._2)
       }
 
-      override def get[T <: Arg[_] : ClassTag]: Option[T] = {
+      override def get[T <: Arg[_]: ClassTag]: Option[T] = {
         val tag = implicitly[ClassTag[T]]
-        args.collect {
-          case tag(t) => t
+        args.collect { case tag(t) =>
+          t
         }.headOption
       }
 
       override def withTargets(targets: Seq[String]) = copy(targets = targets)
       override def serialize: String = (
         args
-        .map(_.serialize)
-         ++ targets
+          .map(_.serialize)
+          ++ targets
       ).mkString(" ")
 
       override def settings: Seq[String] =
         args.map(_.serialize) ++ targets
 
-      private def argsWithout[T <: Arg[_]](
-        implicit tag: ClassTag[T]
-      ): (Option[T], Seq[Arg[_]]) = args.foldLeft[(Option[T], Seq[Arg[_]])]((None, Seq.empty)) {
-        case ((removedElem, rest), tag(t)) => (Some(t), rest)
-        case ((removedElem, rest), elem) => (removedElem, rest :+ elem)
-      }
+      private def argsWithout[T <: Arg[_]](implicit
+          tag: ClassTag[T]
+      ): (Option[T], Seq[Arg[_]]) =
+        args.foldLeft[(Option[T], Seq[Arg[_]])]((None, Seq.empty)) {
+          case ((removedElem, rest), tag(t)) => (Some(t), rest)
+          case ((removedElem, rest), elem)   => (removedElem, rest :+ elem)
+        }
     }
   }
 

scaladoc/resources/dotty_res/scripts/staticsite/alt-details.js

@@ -0,0 +1,18 @@
+// Get all the alt-details-control elements
+const altDetailsControls = document.querySelectorAll('.alt-details-control');
+
+// Loop through each control element
+altDetailsControls.forEach(control => {
+    // Add event listener for 'change' event
+    control.addEventListener('change', function() {
+        // Get the corresponding alt-details-detail element
+        const detailElement = this.nextElementSibling.nextElementSibling;
+
+        // Toggle the display of the detail element based on checkbox state
+        if (this.checked) {
+            detailElement.style.display = 'block';
+        } else {
+            detailElement.style.display = 'none';
+        }
+    });
+});