Merge pull request #13004 from BarkingBad/scaladoc/update-docs

Update the docs, change sidebar url property to page/index

Author: BarkingBad

docs/docs/usage/scaladoc/settings.md

@@ -13,8 +13,12 @@ If you want to know what is current state of compatibility with scaladoc old fla
 
 ## Providing settings
 
-Supply scaladoc settings as command-line arguments, e.g., `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`. If called from sbt,
-update the value of `Compile / doc / scalacOptions`, e. g. `Compile / doc / scalacOptions ++= Seq("-d", "output", "-project", "my-project")`
+Supply scaladoc settings as command-line arguments, e.g., `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`. If called from sbt, update the value of `Compile / doc / scalacOptions` and `Compile / doc / target` respectively, e. g.
+
+```
+Compile / doc / target ++= Seq("-d", "output")
+Compile / doc / scalacOptions ++= Seq("-project", "my-project")
+```
 
 ## Overview of all available settings
 
@@ -118,6 +122,10 @@ A base URL to use as prefix and add `canonical` URLs to all pages. The canonical
 
 A directory containing static files from which to generate documentation. Default directory is `./docs`
 
+##### -no-link-warnings
+
+Suppress warnings for ambiguous or incorrect links in members’ lookup. Doesn't affect warnings for incorrect links of assets etc.
+
 ##### -versions-dictionary-url
 
 A URL pointing to a JSON document containing a dictionary: `version label -> documentation location`.
@@ -134,3 +142,39 @@ Example JSON file:
 }
 ```
 
+##### -snippet-compiler
+
+Snippet compiler arguments provide a way to configure snippet type checking.
+
+This setting accepts a list of arguments in the format:
+args := arg{,arg}
+arg := [path=]flag
+where `path` is a prefix of the path to source files where snippets are located and `flag` is the mode in which snippets will be type checked.
+
+If the path is not present, the argument will be used as the default for all unmatched paths.
+
+Available flags:
+compile - Enables snippet checking.
+nocompile - Disables snippet checking.
+fail - Enables snippet checking, asserts that snippet doesn't compile.
+
+The fail flag comes in handy for snippets that present that some action would eventually fail during compilation, e. g. [Opaques page](docs/reference/other-new-features/opaques.html)
+
+Example usage:
+
+`-snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile`
+
+Which means:
+
+all snippets in files under directory `my/path/nc` should not be compiled at all
+all snippets in files under directory `my/path/f` should fail during compilation
+all other snippets should compile successfully
+
+##### -Ysnippet-compiler-debug
+
+Setting this option makes snippet compiler print the snippet as it is compiled (after wrapping).
+
+##### -Ydocument-synthetic-types
+
+Include pages providing documentation for the intrinsic types (e. g. Any, Nothing) to the docs. The setting is useful only for stdlib because scaladoc for Scala 3 relies on TASTy files, but we cannot provide them for intrinsic types since they are embedded in the compiler.
+All other users should not concern with this setting.

docs/docs/usage/scaladoc/staticSite.md

@@ -2,13 +2,13 @@
 title: Static documentation
 ---
 
-# {{ page.title}}
+# {{ page.title }}
 
-Scaladoc is able to generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/).
-Having a combined tool allows to provide interaction between static documentation and API, thus allowing the two to blend naturally.
+Scaladoc can generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/).
+Having a combined tool allows providing interaction between static documentation and API, thus allowing the two to blend naturally.
 
 Creating a site is just as simple as in Jekyll. The site root contains the
-layout of the site and all files placed there will be either considered static,
+the layout of the site and all files placed there will be either considered static,
 or processed for template expansion.
 
 The files that are considered for template expansion must end in `*.{html,md}`
@@ -29,26 +29,33 @@ index.html
 docs/getting-started.html
 ```
 
-Scaladoc can transform both files and directories (to organize your documentation into tree-like structure). By default directories has title based on file name and has empty content. There is an option to include `index.html` or `index.md` (not both) to provide both content and properties like title (see [Properties](#properties)).
+Scaladoc can transform both files and directories (to organize your documentation into a tree-like structure). By default, directories have a title based on the file name and have empty content. It is possible to provide index pages for each section by creating `index.html` or `index.md` (not both) in the dedicated directory.
 
 ## Properties
 
 Scaladoc uses the [Liquid](https://shopify.github.io/liquid/) templating engine
-and provides a number of custom filters and tags specific to Scala
+and provides several custom filters and tags specific to Scala
 documentation.
 
 In Scaladoc, all templates can contain YAML front-matter. The front-matter
 is parsed and put into the `page` variable available in templates via Liquid.
 
-Scaladoc uses some predefined properties to controls some aspect of page.
+Example front-matter
+```
+---
+title: My custom title
+---
+```
+
+Scaladoc uses some predefined properties to controls some aspects of page.
 
 Predefined properties:
 
- - **title** provide page title that will be used in navigation and html metadata.
- - **extraCss** additional `.css` files that will be included in this page. Paths should be relative to documentation root. **This setting is not exported to template engine.**
- - **extraJs** additional `.js` files that will be included in this page. Paths should be relative to documentation root. **This setting is not exported to template engine.**
- - **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs etc.) but only token html wrapper to provide metadata and resources (js and css files). **This setting is not exported to template engine.**
-- **layout** - predefined layout to use, see below. **This setting is not exported to template engine.**
+ - **title** provide page title that will be used in navigation and HTML metadata.
+ - **extraCss** additional `.css` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.**
+ - **extraJs** additional `.js` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.**
+ - **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs, etc.) but only token HTML wrapper to provide metadata and resources (js and css files). **This setting is not exported to the template engine.**
+- **layout** - predefined layout to use, see below. **This setting is not exported to the template engine.**
 
 
 ## Using existing Templates and Layouts
@@ -99,23 +106,44 @@ Scaladoc by default uses layout of files in `docs` directory to create table of
 ```yaml
 sidebar:
     - title: Blog
-    - title: Docs
-      url: docs/index.html
-    - title: Usage
+    - title: My title
+      page: my-page1.md
+    - page: my-page2.md
+    - page: my-page3/subsection
+    - title: Reference
       subsection:
-        - title: Dottydoc
-          url: docs/usage/dottydoc.html
-        - title: sbt-projects
-          url: docs/usage/sbt-projects.html
+        - page: my-page3.md
+    - index: my-page4/index.md
+      subsection:
+        - page: my-page4/my-page4.md
+    - title: My subsection
+      index: my-page5/index.md
+      subsection:
+        - page: my-page5/my-page5.md
+    - index: my-page6/index.md
+      subsection:
+        - index: my-page6/my-page6/index.md
+          subsection:
+            - page: my-page6/my-page6/my-page6.md
 ```
 
-The `sidebar` key is mandatory, as well as `title` for each element. The
-default table of contents allows you to have subsections - albeit the current
-depth limit is 2 however it accepts both files and directories and latter can be used to provide deeper structures.
+The `sidebar` key is mandatory.
+On each level, you can have three different types of entries: `page`, `blog` or `subsection`.
+
+`page` is a leaf of the structure and accepts the following attributes:
+- `title` (optional) - title of the page
+- `page` (mandatory) - path to the file that will represent the page, it can be either html or markdown file to be rendered, there is also the possibility to pass the `directory` path. If so, the scaladoc will render the directory and all its content as if there were no `sidebar.yml` basing on its tree structure and index files.
+
+The `page` property
 
-The items must provide either `subsection` or `url` but not both at once!
-The only exception is `Blog` which is only a `title` and behaves differently.
-You can read more about blog [here](blog.md).
+`subsection` accepts nested nodes, these can be either pages or subsections, which allow you to create tree-like navigation. The attributes are:
+- `title` (optional) - title of the page
+- `index` (optional) - path to the file that will represent the index file of the subsection, it can be either html or markdown file to be rendered
+- `subsection` (mandatory) - nested nodes, can be either pages or subsections
+
+In `subsection`s, you can omit `title` or `index`, however not specifying any of these properties prevents you from specifying the title of the section.
+
+`blog` is a special node represented by simple entry `- title: Blog` with no other attributes. All your blog posts will be automatically linked under this section. You can read more about the blog [here](blog.md).
 
 ```
 ├── blog
@@ -126,10 +154,29 @@ You can read more about blog [here](blog.md).
 └── sidebar.yml
 ```
 
+## Hierarchy of title
+
+If the title is specified multiple times, the priority is as follows (from highest to lowest priority):
+
+#### Page
+
+1. `title` from the `front-matter` of the markdown/html file
+2. `title` property from the `sidebar.yml` property
+3. filename
+
+#### Subsection
+
+1. `title` from the `front-matter` of the markdown/html index file
+2. `title` property from the `sidebar.yml` property
+3. filename
+
+Note that if you skip the `index` file in your tree structure or you don't specify the `title` in the frontmatter, there will be given a generic name `index`. The same applies when using `sidebar.yml` but not specifying `title` nor `index`, just a subsection. Again, a generic `index` name will appear.
+
+
 ## Static resources
 
 You can attach static resources (pdf, images) to your documentation by using two dedicated directories:
-`resources` and `images`. When you upload your assests under any of these directories you can reference them in markdown
+`resources` and `images`. After placing your assets under any of these directories, you can reference them in markdown
 as if they were relatively at the same level.
 
 For example, consider the following situation:
@@ -151,5 +198,5 @@ For example, consider the following situation:
 You can refer to the assets from within any of the files using markdown links:
 
 ```
-This is my blogpost. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf)
+This is my blog post. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf)
 ```