Migrate to Docusaurus

.github/workflows/ci.yml

@@ -43,5 +43,7 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '17'
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@v2
       - uses: coursier/cache-action@v6
-      - run: sbt site/run
+      - run: sbt site/mdoc

.github/workflows/docs.yml

@@ -10,10 +10,33 @@ jobs:
         with:
           distribution: 'temurin'
           java-version: '17'
+      - uses: actions/setup-node@v4
+      - name: Set up environment
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y fontconfig
+      - name: Checkout the adobe-fonts/source-code-pro
+        uses: actions/checkout@v4
+        with:
+          repository: 'adobe-fonts/source-code-pro'
+          ref: 'release'
+          path: 'fonts/source-code-pro'
+      - name: Install the source-code-pro font
+        run: |
+          fonts_path_from='${{ github.workspace }}/fonts/source-code-pro'
+          fonts_path_to='/usr/share/fonts/source-code-pro'
+          sudo mv "$fonts_path_from" "$fonts_path_to"
+          sudo rm -rf "$fonts_path_to/.git"
+          sudo fc-cache -fv "$fonts_path_to"
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@v2
       - uses: coursier/cache-action@v6
-      - run: sbt site/run
+      - run: sbt site/mdoc
+      - name: Build Docusaurus
+        working-directory: site
+        run: npm install && npm run build
       - uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          enable_jekyll: true
-          publish_dir: ./site-gen/target/mdoc/.
+          enable_jekyll: false
+          publish_dir: ./site/build/.

.gitignore

@@ -1,6 +1,8 @@
 target/
 node_modules/
+site-gen/
 .idea
+site/.docusaurus/
 diagram.png
 slides/
 .vscode

README.md

@@ -2,7 +2,7 @@ Behold, automatically generated diagrams and animations for your data!
 `reftree` is a *Scala* and *Scala.js* library that allows you to
 create data structure visualizations with very little effort.
 
-![teaser](images/teaser.gif)
+![teaser](docs/images/teaser.gif)
 
 There are a few ways you can use `reftree`:
 

build.sbt

@@ -121,41 +121,16 @@ lazy val demoJS = demo.js
   )
 
 val site = project.in(file("site-gen"))
-  .enablePlugins(
-    BuildInfoPlugin,
-    GitBookPlugin,
-    GhpagesPlugin,
-    MdocPlugin,
-    SitePreviewPlugin
-  )
+  .enablePlugins(MdocPlugin, DocusaurusPlugin)
   .dependsOn(demoJVM)
   .settings(commonSettings)
   .settings(
     name := "reftree-site",
     moduleName := "reftree-site",
-    (publish / skip) := true,
-    mdoc := (Compile / run).evaluated,
-    (Compile / mainClass) := Some("reftree.Docs"),
-    (Compile / resources) ++= {
-      List((ThisBuild / baseDirectory).value / "docs")
-    },
-    makeSite / mappings ++= Seq(
-      file("images/teaser.gif") -> "images/teaser.gif",
-      file("images/queue.gif") -> "images/queue.gif",
-      file("images/finger.gif") -> "images/finger.gif",
-      file("images/tree+zipper.gif") -> "images/tree+zipper.gif",
-      (( demoJS / crossTarget).value / "demo-opt.js") -> "js/demo.js"
+    mdocVariables := Map(
+      "VERSION" -> version.value
     ),
-    SiteScaladocPlugin.scaladocSettings( { val Jvm = config("jvm"); Jvm }, coreJVM / (Compile / packageDoc / mappings), "api/jvm"),
-    SiteScaladocPlugin.scaladocSettings( { val Js =  config("js"); Js },  coreJS / (Compile /  packageDoc / mappings), "api/js"),
-    // NameFilter := """.*\.(md|json|css|html)""".r,
-    GitBook / gitbookInstallDir := Some(baseDirectory.value / "node_modules" / "gitbook"),
-    GitBook / sourceDirectory := mdocOut.value,
-    makeSite := makeSite.dependsOn(mdoc.toTask("")).dependsOn(demoJS / ( Compile / fullOptJS)).value,
-    ghpagesNoJekyll := true,
-    git.remoteRepo := "[email protected]:stanch/reftree.git",
-    buildInfoKeys := Seq[BuildInfoKey](version),
-    buildInfoPackage := "reftree.build"
+    (publish / skip) := true
   )
 
 lazy val root = project.in(file("."))

demo/jvm/src/main/scala/reftree/demo/AnimationExamples.scala

@@ -13,7 +13,7 @@ import scala.collection.immutable._
 
 object Queues extends App {
   Logger.root.withHandler(LogHandler(minimumLevel = Some(Level.Trace)))
-  val renderer = Renderer(directory = Paths.get("images"))
+  val renderer = Renderer(directory = Paths.get("docs", "images"))
   import renderer._
 
   Animation
@@ -30,7 +30,7 @@ object FingerTrees extends App {
 
   val renderer = Renderer(
     renderingOptions = RenderingOptions(verticalSpacing = 2, density = 75),
-    directory = Paths.get("images")
+    directory = Paths.get("docs", "images")
   )
   import renderer._
 
@@ -48,7 +48,7 @@ object Zippers extends App {
 
   val renderer = Renderer(
     renderingOptions = RenderingOptions(density = 75),
-    directory = Paths.get("images")
+    directory = Paths.get("docs", "images")
   )
   import renderer._
 
@@ -80,7 +80,7 @@ object Teaser extends App {
   import reftree.contrib.OpticInstances._
   import reftree.contrib.ZipperInstances._
 
-  val renderer = Renderer(directory = Paths.get("images"))
+  val renderer = Renderer(directory = Paths.get("docs", "images"))
   import renderer._
 
   val queues = Animation

docs/GettingStarted.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+---
+
+# Getting started
+
+To use this library you will need to have [GraphViz](http://www.graphviz.org/) installed (and have `dot` on your `PATH`).
+I also recommend to install the [Source Code Pro](https://github.com/adobe-fonts/source-code-pro) fonts (regular and *italic*),
+as I find they look the best among the free options and therefore are used by default.
+
+For viewing PNG and animated GIF on Linux I recommend `eog` and `gifview` respectively.
+
+## Interactive usage
+
+To jump into an interactive session:
+
+```
+$ git clone https://github.com/stanch/reftree
+$ cd reftree
+$ sbt demo
+@ render(List(1, 2, 3))
+// display diagram.png with your favorite image viewer
+```
+
+## Including in your project
+
+You can depend on the library by adding these lines to your `build.sbt`:
+
+```scala
+// JVM
+libraryDependencies += "io.github.stanch" %% "reftree" % "@VERSION@"
+
+// Scala.js
+libraryDependencies += "io.github.stanch" %%% "reftree" % "@VERSION@"
+```
+
+## Minimal example
+
+```scala mdoc:invisible
+val ImagePath = "site-gen/target/mdoc/images"
+```
+
+```scala mdoc:silent
+import reftree.render.{Renderer, RenderingOptions}
+import reftree.diagram.Diagram
+import java.nio.file.Paths
+
+val renderer = Renderer(
+  renderingOptions = RenderingOptions(density = 100),
+  directory = Paths.get(ImagePath, "overview")
+)
+import renderer._
+
+case class Person(firstName: String, age: Int)
+
+Diagram.sourceCodeCaption(Person("Bob", 42)).render("example")
+```
+
+![bob](images/overview/example.png)
+
+For more details, please refer to the [guide](Guide.md).

docs/Guide.md

@@ -1,4 +1,8 @@
-# Guide
+---
+sidebar_position: 3
+---
+
+# User guide
 
 ## Trees
 
@@ -13,23 +17,24 @@ as these instances are readily available or generated on the fly.
 
 You can configure the automatically generated instances like so:
 
-```mdoc:silent
+```scala mdoc:silent
 import reftree.core.ToRefTree
 
 case class Tree(size: Int, value: Int, children: List[Tree])
 
-implicit val treeDerivationConfig = (ToRefTree.DerivationConfig[Tree]
-  .rename("MyTree")                                // display as “MyTree”
-  .tweakField("size", _.withName("s"))             // label the field “s”, instead of “size”
-  .tweakField("value", _.withTreeHighlight(true))  // highlight the value
-  .tweakField("children", _.withoutName))          // do not label the “children” field
+implicit val treeDerivationConfig: ToRefTree.DerivationConfig[Tree] =
+  ToRefTree.DerivationConfig[Tree]
+    .rename("MyTree")                                // display as “MyTree”
+    .tweakField("size", _.withName("s"))             // label the field “s”, instead of “size”
+    .tweakField("value", _.withTreeHighlight(true))  // highlight the value
+    .tweakField("children", _.withoutName)           // do not label the “children” field
 
 implicitly[ToRefTree[Tree]] // auto-derivation will use the configuration above
 ```
 
 For something custom, manual derivation is the way to go, for example:
 
-```mdoc:silent
+```scala mdoc:silent
 import reftree.core._
 
 implicit def treeInstance: ToRefTree[Tree] = ToRefTree[Tree] { tree =>
@@ -50,11 +55,11 @@ To render diagrams and animations, you will need a `Renderer`.
 
 **For JVM:**
 
-```mdoc:invisible
-val ImagePath = "site/target/tut/images"
+```scala mdoc:invisible
+val ImagePath = "site-gen/target/mdoc/images"
 ```
 
-```mdoc:silent
+```scala mdoc:silent
 import reftree.render._
 import reftree.diagram._
 import java.nio.file.Paths
@@ -84,7 +89,7 @@ There are two ways to use renderers:
 
 **JVM**
 
-```mdoc:silent
+```scala mdoc:silent
 import scala.collection.immutable.Queue
 
 // Option 1: using the `render` method
@@ -110,7 +115,7 @@ Diagram(List(1)).render(dom.document.getElementById("diagram"))
 
 You can set various options, for example:
 
-```mdoc:silent
+```scala mdoc:silent
 // using the `render` method
 renderer.tweakRendering(_.withVerticalSpacing(2)).render("queue", Diagram(Queue(1)))
 
@@ -122,35 +127,35 @@ Diagram(Queue(1)).render("queue", _.withVerticalSpacing(2))
 
 Diagrams can be created and combined into bigger diagrams using the following API:
 
-```mdoc:silent
+```scala mdoc:silent
 // no caption
 Diagram(Queue(1)).render("caption-none")
 ```
 
 ![caption-none](images/guide/caption-none.png)
 
-```mdoc:silent
+```scala mdoc:silent
 // automatically set caption to "Queue(1) :+ 2"
 Diagram.sourceCodeCaption(Queue(1) :+ 2).render("caption-source")
 ```
 
 ![caption-source](images/guide/caption-source.png)
 
-```mdoc:silent
+```scala mdoc:silent
 // use toString to get the caption, i.e. "Queue(1, 2)"
 Diagram.toStringCaption(Queue(1) :+ 2).render("caption-tostring")
 ```
 
 ![caption-tostring](images/guide/caption-tostring.png)
 
-```mdoc:silent
+```scala mdoc:silent
 // merge two diagrams, set captions manually
 (Diagram(Queue(1)).withCaption("one") + Diagram(Queue(2)).withCaption("two")).render("one-two")
 ```
 
 ![one-two](images/guide/one-two.png)
 
-```mdoc:silent
+```scala mdoc:silent
 // isolate each diagram in its own namespace (graph nodes will not be shared across them)
 (Diagram(Queue(1)).toNamespace("one") + Diagram(Queue(2)).toNamespace("two")).render("namespaced")
 ```
@@ -162,7 +167,7 @@ Diagram.toStringCaption(Queue(1) :+ 2).render("caption-tostring")
 Animation is essentially a sequence of diagrams, which can be rendered to an animated GIF.
 The simplest way to create an animation is to use the builder API:
 
-```mdoc:silent
+```scala mdoc:silent
 (Animation
   .startWith(Queue(1))
   .iterateWithIndex(2)((queue, i) => queue :+ (i + 1))
@@ -174,7 +179,7 @@ The simplest way to create an animation is to use the builder API:
 
 You can also configure how the diagram for each frame is produced:
 
-```mdoc:silent
+```scala mdoc:silent
 (Animation
   .startWith(Queue(1))
   .iterateWithIndex(2)((queue, i) => queue :+ (i + 1))
@@ -189,7 +194,7 @@ all tree nodes across animation frames. Sometimes you want to “anchor”
 the root of the data structure instead, to force it to stay still
 while everything else is moving. You can achieve this via `withAnchor` method:
 
-```mdoc:silent
+```scala mdoc:silent
 (Animation
   .startWith(Queue(1))
   .iterateWithIndex(2)((queue, i) => queue :+ (i + 1))
@@ -201,7 +206,7 @@ while everything else is moving. You can achieve this via `withAnchor` method:
 
 Finally, animations can be combined in sequence or in parallel, for example:
 
-```mdoc:silent
+```scala mdoc:silent
 val queue1 = (Animation
   .startWith(Queue(1))
   .iterateWithIndex(2)((queue, i) => queue :+ (i + 1))