Update user manual for scaladoc

Author: BarkingBad

NOTICE.md

@@ -82,9 +82,9 @@ major authors were omitted by oversight.
     modifications. They were originally authored by Lex Spoon, Som Snytt,
     Adriaan Moors, Paul Phillips and others.
 
-  * dotty.tools.dottydoc: The Dottydoc documentation utility ships some
+  * dotty.tools.scaladoc: The Scaladoc documentation utility ships some
     third-party JavaScript and CSS libraries which are located under
-    dotty-doc/resources/css/, dotty-doc/resources/js/, docs/css/ and
+    scaladoc/resources/dotty_res/styles/, scaladoc/resources/dotty_res/scripts/, docs/css/ and
     docs/js/. Please refer to the license header of the concerned files for
     details.
 

compiler/src/dotty/tools/dotc/config/Printers.scala

@@ -20,7 +20,7 @@ object Printers {
   val debug = noPrinter
   val derive = noPrinter
   val desugar = noPrinter
-  val dottydoc = noPrinter
+  val scaladoc = noPrinter
   val exhaustivity = noPrinter
   val gadts = noPrinter
   val gadtsConstr = noPrinter

compiler/src/dotty/tools/dotc/config/ScalaSettings.scala

@@ -213,9 +213,6 @@ class ScalaSettings extends Settings.SettingGroup with CommonScalaSettings {
 
   val YforceInlineWhileTyping: Setting[Boolean] = BooleanSetting("-Yforce-inline-while-typing", "Make non-transparent inline methods inline when typing. Emulates the old inlining behavior of 3.0.0-M3.")
 
-  /** Dottydoc specific settings that are not used in scaladoc */
-  val docSnapshot: Setting[Boolean] = BooleanSetting("-doc-snapshot", "Generate a documentation snapshot for the current Dotty version")
-
   val projectUrl: Setting[String] = StringSetting (
     "-project-url",
     "project repository homepage",

compiler/src/dotty/tools/dotc/core/Comments.scala

@@ -143,7 +143,7 @@ object Comments {
    * @author Felix Mulder
    */
   class CommentExpander {
-    import dotc.config.Printers.dottydoc
+    import dotc.config.Printers.scaladoc
     import scala.collection.mutable
 
     def expand(sym: Symbol, site: Symbol)(using Context): String = {
@@ -203,7 +203,7 @@ object Comments {
         case None =>
           // SI-8210 - The warning would be false negative when this symbol is a setter
           if (ownComment.indexOf("@inheritdoc") != -1 && ! sym.isSetter)
-            dottydoc.println(s"${sym.span}: the comment for ${sym} contains @inheritdoc, but no parent comment is available to inherit from.")
+            scaladoc.println(s"${sym.span}: the comment for ${sym} contains @inheritdoc, but no parent comment is available to inherit from.")
           ownComment.replace("@inheritdoc", "<invalid inheritdoc annotation>")
         case Some(sc) =>
           if (ownComment == "") sc
@@ -317,7 +317,7 @@ object Comments {
                 val sectionTextBounds = extractSectionText(parent, section)
                 cleanupSectionText(parent.substring(sectionTextBounds._1, sectionTextBounds._2))
               case None =>
-                dottydoc.println(s"""${sym.span}: the """" + getSectionHeader + "\" annotation of the " + sym +
+                scaladoc.println(s"""${sym.span}: the """" + getSectionHeader + "\" annotation of the " + sym +
                     " comment contains @inheritdoc, but the corresponding section in the parent is not defined.")
                 "<invalid inheritdoc annotation>"
             }
@@ -384,7 +384,7 @@ object Comments {
                 lookupVariable(vname, site) match {
                   case Some(replacement) => replaceWith(replacement)
                   case None              =>
-                    dottydoc.println(s"Variable $vname undefined in comment for $sym in $site")
+                    scaladoc.println(s"Variable $vname undefined in comment for $sym in $site")
                 }
             }
           }

compiler/src/dotty/tools/dotc/util/CommentParsing.scala

@@ -8,11 +8,11 @@ package dotty.tools.dotc.util
 import scala.collection.mutable
 
 /** The comment parsing in `dotc` is used by both the comment cooking and the
-  * dottydoc tool.
+  * scaladoc tool.
   *
   * The comment cooking is used to expand comments with `@inheritdoc` and
   * `@define` annotations. The rest of the comment is untouched and later
-  * handled by dottydoc.
+  * handled by scaladoc.
   */
 object CommentParsing {
   import Chars._

docs/docs/usage/scaladoc/blog.md

@@ -7,3 +7,33 @@ title: Built-in blog
 Scaladoc allows you to include a simple blog in your documentation. For now, it
 provides only basic features. In the future, we plan to include more advanced
 features like tagging or author pages.
+
+Blog is treated a little differently than regular static sites. This article will help you set up your own blog.
+
+## Proper directory setup
+
+All your blogposts must be put under `blog/_posts` directory.
+
+
+```
+├── blog
+│   ├── _posts
+│   │   └── 2016-12-05-implicit-function-types.md
+│   └── index.html
+```
+
+If you are using sidebar don't forget to place
+
+```
+sidebar:
+    - title: Blog
+```
+
+somewhere inside the tree. Scaladoc will attach under that section all of your blogposts.
+
+## Naming convention
+
+All the blogpost filenames should start with date in numeric format matching `YYYY-MM-DD`.
+Example name is `2015-10-23-dotty-compiler-bootstraps.md`.
+
+

docs/docs/usage/scaladoc/settings.md

@@ -0,0 +1,113 @@
+---
+title: Scaladoc settings
+---
+
+# {{page.title}}
+
+You can find brief information included in this chapter while calling scaladoc with `-help` flag. However it can be a little tricky if one uses sbt `doc` task.
+
+## Parity with scaladoc for Scala 2
+
+Scaladoc has been rewritten from scratch and some of the features turned out to be useless in the new context.
+If you want to know what is current state of compatibility with scaladoc old flags, you can visit this issue for tracking [progress](https://github.com/lampepfl/dotty/issues/11907).
+
+## Providing settings
+
+Scaladoc accepts settings provided as a string, e. g. `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes` or, if called from sbt,
+update the value of `Compile / doc / scalacOptions`, e. g. `Compile / doc / scalacOptions ++= Seq("-d", "output", "-project", "my-project")`
+
+## Overview of all available settings
+
+##### -project
+The name of the project. To provide compatibility with Scala2 aliases with `-doc-title`
+
+##### -project-version
+The current version of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-version`
+
+##### -project-logo
+The logo of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-logo`
+
+##### -project-footer
+The string message that appears in a footer section. To provide compatibility with Scala2 aliases with `-doc-footer`
+
+##### -comment-syntax
+The default syntax of comments. Defaults to markdown however wikisyntax can be used.
+
+##### -revision
+Revision (branch or ref) used to build project project. Useful with sourcelinks to prevent them from pointing always to the newest master that is subject to changes.
+
+##### -source-links
+Source links provide a mapping between file in documentation and code repository.
+
+Accepted formats:
+<\sub-path>=<\source-link>
+<\source-link>
+
+where <\source-link> is one of following:
+ - `github://<organization>/<repository>[/revision][#subpath]`
+     will match https://github.com/$organization/$repository/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber]
+     when revision is not provided then requires revision to be specified as argument for scaladoc
+ - `gitlab://<organization>/<repository>`
+     will match https://gitlab.com/$organization/$repository/-/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber]
+     when revision is not provided then requires revision to be specified as argument for scaladoc
+ - <\scaladoc-template>
+
+<scaladoc-template> is a format for `doc-source-url` parameter scaladoc.
+NOTE: We only supports `€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`,
+ €{FILE_PATH}, and €{FILE_LINE} patterns
+
+
+Template can defined only by subset of sources defined by path prefix represented by `<sub-path>`.
+In such case paths used in templates will be relativized against `<sub-path>`
+
+Example source links is:
+`-source-links:docs=github://lampepfl/dotty/master#docs`
+
+
+##### -external-mappings
+
+Mapping between regexes matching classpath entries and external documentation.
+'regex::\[scaladoc|scaladoc|javadoc]::path' syntax is used
+
+Example external mapping is:
+`-external-mappings:.*scala.*::scaladoc3::http://dotty.epfl.ch/api/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/`
+
+##### -social-links
+
+Links to social sites. '[github|twitter|gitter|discord]::link' syntax is used. 'custom::link::white_icon_name::black_icon_name' is also allowed, in this case icons must be present in 'images/'' directory.
+
+Example social link is:
+
+`-social-links:github::https://github.com/lampepfl/dotty,gitter::https://gitter.im/scala/scala,twitter::https://twitter.com/scala_lang`
+
+##### -skip-by-id
+
+Identifiers of packages or top-level classes to skip when generating documentation.
+
+##### -skip-by-regex
+
+Regexes that match fully qualified names of packages or top-level classes to skip when generating documentation.
+
+##### -doc-root-content
+
+The file from which the root package documentation should be imported.
+
+##### -author
+
+Include authors.
+
+##### -groups
+
+Group similar functions together (based on the @group annotation)
+
+##### -private
+
+Show all types and members. Unless specified, show only public and protected types and members.
+
+##### -doc-canonical-base-url
+
+A base URL to use as prefix and add `canonical` URLs to all pages. The canonical URL may be used by search engines to choose the URL that you want people to see in search results. If unset no canonical URLs are generated.
+
+##### -siteroot
+
+A directory containing static files from which to generate documentation. Default directory is `./docs`

docs/docs/usage/scaladoc/staticSite.md

@@ -92,14 +92,13 @@ Layouts must be placed in a `_layouts` directory in the site root:
 └── index.html
 ```
 
-Sidebar
-=======
+## Sidebar
+
 Scaladoc by default uses layout of files in `docs` directory to create table of content. There is also ability to override it by providing a `sidebar.yml` file in the site root:
 
 ```yaml
 sidebar:
     - title: Blog
-      url: blog/index.html
     - title: Docs
       url: docs/index.html
     - title: Usage
@@ -114,12 +113,43 @@ 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 items which have on the `subsection` level does not accepts `url`.
+The items must provide either `subsection` or `url` but not both at once!
+The only excepiton is `Blog` which is only a `title` and behaves differently.
+You can read more about blog [here](blog.md).
 
 ```
 ├── blog
-│   └── _posts
-│       └── 2016-12-05-implicit-function-types.md
+│   ├── _posts
+│   │   └── 2016-12-05-implicit-function-types.md
+│   └── index.html
 ├── index.html
 └── sidebar.yml
 ```
+
+## Static resources
+
+You can attach static resources (pdf, images) in your documentation using two dedicated directories:
+`resources` and `images`. When you upload your assests under any of these directories you can reference them in markdown
+as if they were relatively at the same level.
+
+For example let's look at this situation:
+
+```
+├── blog
+│   ├── _posts
+│   │   └── 2016-12-05-implicit-function-types.md
+│   └── index.html
+├── index.html
+├── resources
+│   └── my_file.pdf
+├── images
+│   └── my_image.png
+└── sidebar.yml
+
+```
+
+You can access them directly inside 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)
+```

docs/sidebar.yml

@@ -1,6 +1,5 @@
 sidebar:
     - title: Blog
-      url: blog/index.html
     - title: Usage
       subsection:
         - title: Getting Started
@@ -17,8 +16,6 @@ sidebar:
           url: docs/usage/cbt-projects.html
         - title: Scaladoc
           url: docs/usage/scaladoc
-        - title: Dottydoc [Legacy]
-          url: docs/usage/dottydoc.html
     - title: Reference
       subsection:
         - title: Overview

sbt-dotty/src/dotty/tools/sbtplugin/DottyPlugin.scala

@@ -287,7 +287,7 @@ object DottyPlugin extends AutoPlugin {
       //    classpath, because we need all of those to actually run the compiler.
       //    NOTE: All of those should have the *same version* (equal to scalaVersion
       //    for everything but scala-library).
-      //    (Complication: because dottydoc is a separate artifact with its own dependencies,
+      //    (Complication: because scaladoc is a separate artifact with its own dependencies,
       //     running it requires putting extra dependencies on the _JVM_ classpath)
       //
       // 3. scala-library, dotty-library on the _compiler_ bootclasspath or