Add docs.

build.sbt

@@ -122,6 +122,37 @@ lazy val docs = project
   .dependsOn(core.jvm)
   .settings(
     mdocVariables += ("SCALAJS_VERSION" -> scalaJSVersion),
+    libraryDependencies ~= { old =>
+      old.map { dependency =>
+        if (
+          dependency.organization == "org.scalameta" && dependency.name == "mdoc"
+        ) {
+          dependency
+            .exclude(
+              "com.lihaoyi",
+              "sourcecode_3"
+            )
+            .exclude(
+              "com.lihaoyi",
+              "fansi_3"
+            )
+            .exclude(
+              "org.scalameta",
+              "mdoc-parser_3"
+            )
+            .exclude(
+              "org.typelevel",
+              "paiges-core_3"
+            )
+            .exclude(
+              "org.scala-lang.modules",
+              "scala-collection-compat_3"
+            )
+        } else {
+          dependency
+        }
+      }
+    },
     tlSiteKeepFiles := false,
     tlSiteHelium := tlSiteHelium.value.site
       .mainNavigation(

core/js/src/main/scala/aquascape/PlatformCompanion.scala

@@ -19,8 +19,15 @@ package aquascape
 import cats.effect.*
 import doodle.svg.*
 import doodle.syntax.all.*
+import org.scalajs.dom
 
 trait PlatformCompanion {
+
+  def writeCode(text: String, name: String): IO[Unit] = for {
+    codeEl <- IO(dom.document.getElementById(s"${name}Code"))
+    _ <- IO(codeEl.textContent = text)
+  } yield ()
+
   def draw(picture: Picture[Unit], name: String): IO[Unit] =
     picture.drawWithFrameToIO(Frame(name))
 }

core/jvm/src/main/scala/aquascape/PlatformCompanion.scala

@@ -26,7 +26,7 @@ import fs2.Stream
 
 trait PlatformCompanion {
 
-  def code(text: String, name: String): IO[Unit] =
+  def writeCode(text: String, name: String): IO[Unit] =
     Files[IO].writeUtf8(Path(s"$name.txt"))(Stream(text)).compile.drain
   def draw(picture: Picture[Unit], name: String): IO[Unit] =
     picture.writeToIO[Png](s"$name.png")

core/shared/src/main/scala/aquascape/AquascapeApp.scala

@@ -17,7 +17,6 @@
 package aquascape
 
 import aquascape.drawing.Config
-import aquascape.code.StreamCode
 import cats.effect.*
 import cats.syntax.all.*
 
@@ -28,9 +27,16 @@ trait Aquascape {
 
   def config: Config = Config.default
 
-  def stream(using Scape[IO]): IO[Unit]
+  def streamCode(using Scape[IO]): StreamCode
+}
+
+object Aquascape {
+  trait Simple extends Aquascape {
+    def stream(using Scape[IO]): IO[Unit]
 
-  def streamCode(using Scape[IO]): StreamCode = StreamCode(code = None, stream = stream)
+    final def streamCode(using Scape[IO]): StreamCode =
+      StreamCode(code = None, stream = stream)
+  }
 }
 
 object AquascapeApp extends PlatformCompanion {
@@ -47,6 +53,7 @@ object AquascapeApp extends PlatformCompanion {
     given Scape[IO] = scape
     streamCode = args.streamCode(using scape)
     picture <- streamCode.stream.draw(args.config)
+    _ <- streamCode.code.traverse_(writeCode(_, args.name))
     _ <- draw(picture, args.name)
   } yield ()
 
@@ -60,14 +67,14 @@ object AquascapeApp extends PlatformCompanion {
             aquascape.name,
             aquascape.chunked,
             aquascape.config,
-            aquascape.stream
+            aquascape.streamCode
           )
         )
       )
   }
 }
 
-trait AquascapeApp extends IOApp.Simple with Aquascape {
+trait AquascapeApp extends IOApp.Simple with Aquascape.Simple {
   final def run: IO[Unit] =
     AquascapeApp.run(AquascapeApp.Args(name, chunked, config, streamCode))
 }

core/shared/src/main/scala/aquascape/code.scala

@@ -0,0 +1,9 @@
+package aquascape
+
+import cats.effect.IO
+
+final case class StreamCode(code: Option[String], stream: IO[Any])
+
+inline def code(stream: IO[Any]): StreamCode = ${
+  aquascape.codemacro.codeImpl('stream)
+}

core/shared/src/main/scala/aquascape/code/CodeMacro.scala → core/shared/src/main/scala/aquascape/codemacro/CodeMacro.scala

@@ -14,20 +14,16 @@
  * limitations under the License.
  */
 
-package aquascape.code
-
+package aquascape.codemacro
+import aquascape.StreamCode
 import cats.effect.IO
 import org.scalafmt.Scalafmt
 import org.scalafmt.config.ScalafmtConfig
 
 import scala.meta.*
 import scala.quoted.*
 
-final case class StreamCode(code: Option[String], stream: IO[Any])
-
-inline def code(stream: IO[Any]): StreamCode = ${ codeImpl('stream) }
-
-private def codeImpl(
+def codeImpl(
     stream: Expr[IO[Any]]
 )(using q: Quotes): Expr[StreamCode] = {
   import q.reflect.*

docs/how-to-write-the-diagrams.md

@@ -123,7 +123,7 @@ import aquascape.*
 import cats.effect.*
 import fs2.*
 
-val firstAquascape = new Aquascape {
+val firstAquascape = new Aquascape.Simple {
   def name: String = "firstFrame"
   def stream(using Scape[IO]): IO[Unit] = {
     Stream(1, 2, 3)
@@ -137,7 +137,7 @@ val firstAquascape = new Aquascape {
   }
 }
 
-val secondAquascape = new Aquascape {
+val secondAquascape = new Aquascape.Simple {
   def name: String = "secondFrame"
   def stream(using Scape[IO]): IO[Unit] = {
     Stream(4, 5, 6)
@@ -170,6 +170,53 @@ object App extends AquascapeApp.Batch {
   </body>
 </html>
 ```
+## How to export code snippets
+
+You can export code snippets along with their aquascapes using the `streamCode` and `code` functions. These come in handy when embedding aquascapes into blog posts and docs.
+
+@:todo(This snippet must be manually checked due to classpath issues when running scalafmt)
+```scala
+// App.scala
+//> using dep com.github.zainab-ali::aquascape::@VERSION@
+
+import aquascape.*
+import cats.effect.*
+import fs2.*
+
+val basicScape = new Aquascape { // Extend `Aquascape` instead of `Aquascape.Simple`
+  def name: String = "aquascapeFrame"
+  def streamCode(using Scape[IO]): StreamCode = code { // Call the `code` macro
+    Stream(1, 2, 3)
+      .stage("Stream(1, 2, 3)")
+      .compile
+      .toList
+      .compileStage(
+        "compile.toList"
+      )
+      .void
+  }
+}
+
+object App extends AquascapeApp.Batch {
+  val aquascapes: List[Aquascape] = List(basicScape)
+}
+```
+
+### Embedding code snippets in HTML
+
+[Package the app](#embed-an-svg-in-html) as before, then include it in HTML along with a `<code>` element. The `<code>` element must have an id corresponding to the aquascape:
+
+```html
+<html>
+  <head>
+    <script src="App.js" type="text/javascript"></script>
+  </head>
+  <body>
+    <code id="aquascapeFrameCode"></code>
+    <div id="aquascapeFrame"></div>
+  </body>
+</html>
+```
 
 ## Best practices