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
+
+Avoid warnings for ambiguous and incorrect links in members look up. 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,28 @@ Example JSON file:
 }
 ```
 
+##### -snippet-compiler
+
+Snippet compiler arguments provide a way to configure snippet checking.
+
+This setting accept list of arguments in format:
+args := arg{,arg}
+arg := [path=]flag
+where path is a prefix of source paths to members to which argument should be set.
+
+If path is not present, argument will be used as default.
+
+Available flags:
+compile - Enables snippet checking.
+nocompile - Disables snippet checking.
+fail - Enables snippet checking, asserts that snippet doesn't compile.
+
+You can read more about snippet compiler [here](snippetCompiler.md)
+
+##### -Ysnippet-compiler-debug
+
+Setting this option causes snippet compiler to print snippet as it is compiled (after wrapping).
+
+##### -Ydocument-synthetic-types
+
+Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib

docs/docs/usage/scaladoc/snippetCompiler.md

@@ -0,0 +1,5 @@
+---
+title: Snippet compiler
+---
+
+# Snippet compiler - new way to validate your docs

docs/docs/usage/scaladoc/staticSite.md

@@ -40,6 +40,13 @@ 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.
 
+Example front-matter
+```
+---
+title: My custom title
+---
+```
+
 Scaladoc uses some predefined properties to controls some aspect of page.
 
 Predefined properties:
@@ -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 following attributes:
+- `title` \[optional\] - title of the page
+- `page` \[mandatory\] - path to the file that will represent the page, it can be either html of markdown file to be rendered, there is also 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 of 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 subsection, 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 of markdown file to be rendered
+- `subsection` \[mandatory\] - nested nodes, can be either pages or subsections
+
+The `Subsection` can omit `title` or `index`, however not specifying any of these properties disables you from giving the title of the section.
+
+The `Blog` is a special node represented by simple entry `- title: Blog` with no other attirbutes. All your blogposts will be automatically linked under this section. You can read more about blog [here](blog.md).
 
 ```
 ├── blog
@@ -126,6 +154,25 @@ You can read more about blog [here](blog.md).
 └── sidebar.yml
 ```
 
+## Hierarchy of title
+
+There is a possibility to give custom title using `sidebar.yml`. The default strategy when choosing title for:
+
+#### 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 `index` file in your tree structure of you don't specify the `title` in the frontmatter, there will be given generic name `index`. The same applies when using `sidebar.yml` but not specifying `title` nor `index`, just a subsection. Again, generic `index` name will appear.
+
+
 ## Static resources
 
 You can attach static resources (pdf, images) to your documentation by using two dedicated directories: