Add documentation snapshotting capability

Author: anatoliykmetyuk

.drone.yml

@@ -124,6 +124,27 @@ steps:
     target:
     - nightly
 
+- name: nightly_documentation
+  pull: default
+  image: lampepfl/dotty:2020-01-22-2
+  depends_on:
+  - test
+  - test_bootstrapped
+  - community_build
+  - test_java11
+  - publish_nightly
+  commands:
+  - ./project/scripts/genDocs -doc-snapshot
+  environment:
+    BOT_TOKEN:
+      from_secret: bot_token
+    NIGHTLYBUILD: yes
+  when:
+    event:
+    - promote
+    target:
+    - nightly
+
 - name: publish_release
   pull: default
   image: lampepfl/dotty:2020-01-22-2
@@ -150,6 +171,26 @@ steps:
     event:
     - tag
 
+- name: release_documentation
+  pull: default
+  image: lampepfl/dotty:2020-01-22-2
+  depends_on:
+  - test
+  - test_bootstrapped
+  - community_build
+  - test_java11
+  - publish_release
+  - github_release
+  commands:
+  - ./project/scripts/genDocs -doc-snapshot
+  environment:
+    BOT_TOKEN:
+      from_secret: bot_token
+    RELEASEBUILD: yes
+  when:
+    event:
+    - tag
+
 - name: github_release
   pull: default
   image: plugins/github-release

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

@@ -215,5 +215,7 @@ class ScalaSettings extends Settings.SettingGroup {
     ""
   )
 
+  val docSnapshot: Setting[Boolean] = BooleanSetting("-doc-snapshot", "Generate a documentation snapshot for the current Dotty version")
+
   val wikiSyntax: Setting[Boolean] = BooleanSetting("-Xwiki-syntax", "Retains the Scala2 behavior of using Wiki Syntax in Scaladoc.")
 }

doc-tool/src/dotty/tools/dottydoc/DocDriver.scala

@@ -1,6 +1,8 @@
 package dotty.tools
 package dottydoc
 
+import java.io.File
+
 import dotty.tools.dottydoc.util.syntax._
 import core.ContextDottydoc
 import dotc.core.Contexts._
@@ -38,22 +40,26 @@ class DocDriver extends Driver {
     implicit val ctx: Context = ictx
     val reporter = doCompile(newCompiler, filesToDocument)
 
-    val siteRoot = new java.io.File(ctx.settings.siteRoot.value)
+    val siteRoot = File(ctx.settings.siteRoot.value)
     val projectName = ctx.settings.projectName.value
     val projectVersion = ctx.settings.projectVersion.value
     val projectUrl = Option(ctx.settings.projectUrl.value).filter(_.nonEmpty)
     val projectLogo = Option(ctx.settings.projectLogo.value).filter(_.nonEmpty)
+    val docSnapshot = ctx.settings.docSnapshot.value
+
+    var outDir = File(siteRoot, "_site")
+    if docSnapshot then outDir = File(outDir, projectVersion)
 
     if (projectName.isEmpty)
       ctx.error(s"Site project name not set. Use `-project <title>` to set the project name")
     else if (!siteRoot.exists || !siteRoot.isDirectory)
       ctx.error(s"Site root does not exist: $siteRoot")
     else {
       Site(siteRoot, projectName, projectVersion, projectUrl, projectLogo, ctx.docbase.packages)
-        .generateApiDocs()
-        .copyStaticFiles()
-        .generateHtmlFiles()
-        .generateBlog()
+        .generateApiDocs(outDir)
+        .copyStaticFiles(outDir)
+        .generateHtmlFiles(outDir)
+        .generateBlog(outDir)
 
       ctx.docbase.printSummary()
     }

doc-tool/src/dotty/tools/dottydoc/staticsite/Site.scala

@@ -128,10 +128,7 @@ case class Site(
     new SourceFile(virtualFile, Codec.UTF8)
   }
 
-  /** Copy static files to `outDir` */
-  private[this] val defaultOutDir = new JFile(root.getAbsolutePath + JFile.separator + "_site")
-
-  def copyStaticFiles(outDir: JFile = defaultOutDir)(implicit ctx: Context): this.type =
+  def copyStaticFiles(outDir: JFile)(implicit ctx: Context): this.type =
     createOutput (outDir) {
       // Copy user-defined static assets
       staticAssets.foreach { asset =>
@@ -197,7 +194,7 @@ case class Site(
   }
 
   /** Generate HTML for the API documentation */
-  def generateApiDocs(outDir: JFile = defaultOutDir)(implicit ctx: Context): this.type =
+  def generateApiDocs(outDir: JFile)(implicit ctx: Context): this.type =
     createOutput(outDir) {
       def genDoc(e: model.Entity): Unit = {
         ctx.docbase.echo(s"Generating doc page for: ${e.path.mkString(".")}")
@@ -243,7 +240,7 @@ case class Site(
     }
 
   /** Generate HTML files from markdown and .html sources */
-  def generateHtmlFiles(outDir: JFile = defaultOutDir)(implicit ctx: Context): this.type =
+  def generateHtmlFiles(outDir: JFile)(implicit ctx: Context): this.type =
     createOutput(outDir) {
       compilableFiles.foreach { asset =>
         val pathFromRoot = stripRoot(asset)
@@ -263,7 +260,7 @@ case class Site(
     }
 
   /** Generate blog from files in `blog/_posts` and output in `outDir` */
-  def generateBlog(outDir: JFile = defaultOutDir)(implicit ctx: Context): this.type =
+  def generateBlog(outDir: JFile)(implicit ctx: Context): this.type =
     createOutput(outDir) {
       blogposts.foreach { file =>
         val BlogPost.extract(year, month, day, name, ext) = file.getName

project/Build.scala

@@ -130,7 +130,7 @@ object Build {
   val dotr = inputKey[Unit]("run compiled binary using the correct classpath, or the user supplied classpath")
 
   // Compiles the documentation and static site
-  val genDocs = taskKey[Unit]("run dottydoc to generate static documentation site")
+  val genDocs = inputKey[Unit]("run dottydoc to generate static documentation site")
 
   // Shorthand for compiling a docs site
   val dottydoc = inputKey[Unit]("run dottydoc")
@@ -409,7 +409,9 @@ object Build {
 
     javaOptions ++= (javaOptions in `dotty-compiler`).value,
 
-    genDocs := Def.taskDyn {
+    genDocs := Def.inputTaskDyn {
+      val dottydocExtraArgs = spaceDelimited("<arg>").parsed
+
       // Make majorVersion available at dotty.epfl.ch/versions/latest-nightly-base
       // Used by sbt-dotty to resolve the latest nightly
       val majorVersion = baseVersion.take(baseVersion.lastIndexOf('.'))
@@ -427,11 +429,11 @@ object Build {
         "-project-logo", "dotty-logo.svg",
         "-classpath", dottydocClasspath.value,
         "-Yerased-terms"
-      )
+      ) ++ dottydocExtraArgs
       (runMain in Compile).toTask(
         s""" dotty.tools.dottydoc.Main ${args.mkString(" ")} ${sources.mkString(" ")}"""
       )
-    }.value,
+    }.evaluated,
 
     dottydoc := Def.inputTaskDyn {
       val args = spaceDelimited("<arg>").parsed

project/scripts/genDocs

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 
 # Usage:
-# BOT_TOKEN=<dotty-bot password> ./genDocs
+# BOT_TOKEN=<dotty-bot password> ./genDocs [-doc-snapshot]
 
 set -e
+GENDOC_EXTRA_ARGS=$@
 
 # set extended glob, needed for rm everything but x
 shopt -s extglob
@@ -18,7 +19,7 @@ echo "Working directory: $PWD"
 
 # this command will generate docs in $PWD/docs/_site
 SBT="$(cd "$(dirname "${BASH_SOURCE[0]}")" >& /dev/null && pwd)/sbt"
-"$SBT" "genDocs"
+"$SBT" "genDocs $GENDOC_EXTRA_ARGS"
 
 # make sure that the previous command actually succeeded
 if [ ! -d "$PWD/docs/_site" ]; then
@@ -39,6 +40,9 @@ git config user.email "[email protected]"
 git fetch doc-remote gh-pages
 git checkout gh-pages
 
+# save the old snapshots to the newly generated site
+mv 0.*/ $PWD/docs/_site
+
 # move newly generated _site dir to $PWD
 mv $PWD/docs/_site .