Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Some progress towards fixing mdocs #70

Closed
wants to merge 5 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions build.sbt
Original file line number Diff line number Diff line change
Expand Up @@ -170,16 +170,17 @@ lazy val jsdocs =
.settings(
neverPublish,
organization := "io.indigoengine",
libraryDependencies += "org.scala-js" %%% "scalajs-dom" % Dependancies.scalajsDomVersion
libraryDependencies += "org.scala-js" %%% "scalajs-dom" % Dependancies.scalajsDomVersion,
scalaJSLinkerConfig ~= { _.withModuleKind(ModuleKind.CommonJSModule) }
)
.dependsOn(tyrian.js)
.dependsOn(tyrianIO.js)
// .dependsOn(tyrianIndigoBridge.js)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd really like to switch this for "io.indigoengine" %%% "tyrian" % tyrianDocsVersion ideally, the current in dev version is the one I want the docs checked against. Feels like that should work but it threw up new problems for me.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah but I guess that won't work because they're all published against a later version of Scala.js.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I wouldn't take any of the changes in this PR too seriously :) mainly, it's to demonstrate that things should work and hopefully help track down that mdoc regression in the latest release.

.enablePlugins(ScalaJSPlugin)

lazy val docs =
project
.in(file("tyrian-docs"))
.dependsOn(tyrian.js)
.dependsOn(tyrianIO.js)
.dependsOn(tyrianIndigoBridge.js)
.enablePlugins(MdocPlugin)
.settings(
neverPublish,
Expand All @@ -192,6 +193,7 @@ lazy val docs =
"SCALA_VERSION" -> scalaDocsVersion
)
)
.dependsOn(tyrian.jvm)
.settings(
run / fork := true
)
Expand Down
8 changes: 4 additions & 4 deletions docs/concepts/cmd.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Commands can be produced as part of a result of calling the `init` or `updateMod

Here is an example in which, on receiving a message `Msg.LogThis`, we are not going to change the model, but we want to write to the browser's JavaScript console:

```scala mdoc:silent
```scala mdoc:js:shared
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copying from Discord for posterity:

That file only has :shared and :compile-only modifiers - which means that there's no entry points to actually run the JavaScript code - which means it's probably being eliminated by the linker - which means it produced no JavaScript files, which in turn crashes the modifier.

Just changing one of the blocks from mdoc:js:compile-only to mdoc:js actually fixes the generation with Mdoc 2.3.1 and Scala.js 1.9.0.
I changed this one: https://github.com/PurpleKingdomGames/tyrian/pull/70/files#diff-c35eaeeeac3890e0c4181f6aebc4d5048b37049123f63dd434b48191d75dfad9R58

import tyrian.*
import tyrian.cmds.*
import cats.effect.IO
Expand All @@ -56,7 +56,7 @@ def update(msg: Msg, model: Model): (Model, Cmd[IO, Msg]) =

To achieve this, we use the `Logger` command that comes with Tyrian. The `Logger` command is in fact just a `Cmd.SideEffect` that captures a value or behavior as a zero argument function, known as a `thunk`, in this case a simplified implementation could just be:

```scala mdoc:silent
```scala mdoc:js:compile-only
def consoleLog(msg: String): Cmd[IO, Nothing] =
Cmd.SideEffect {
println(msg)
Expand All @@ -65,13 +65,13 @@ def consoleLog(msg: String): Cmd[IO, Nothing] =

But commands can also return values in the form of messages. The `Random` command looks like this:

```scala
```scala mdoc:js:compile-only
Random.double
```

...and produces an instance of `RandomValue`, but this leads to a problem since `RandomValue` is almost certainly not your app's `Msg` type, and so we must map over the result:

```scala
```scala mdoc:js:compile-only
enum MyMsg:
case MyRandom(d: Double) extends MyMsg

Expand Down
28 changes: 13 additions & 15 deletions docs/concepts/guided-tour.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ The example is comprised of two buttons, `+` and `-`, and some text that shows a

The version of this in the [examples](https://github.com/PurpleKingdomGames/tyrian/tree/main/examples) is already quite lean, but the version below has been stripped back to the minimum.

```scala mdoc:silent
```scala mdoc:js:compile-only
import tyrian.Html.*
import tyrian.*
import cats.effect.IO
Expand Down Expand Up @@ -85,15 +85,15 @@ Our app is a counter, so we need a number we can increment and decrement. In thi

To use our model, we're going to have to initialize it!

```scala mdoc:reset:invisible
```scala mdoc:js:shared:invisible
import tyrian.Html.*
import tyrian.*
import cats.effect.IO

type Model = Int
```

```scala mdoc:silent
```scala mdoc:js:compile-only
def init(flags: Map[String, String]): (Model, Cmd[IO, Msg]) =
(0, Cmd.Empty)
```
Expand All @@ -111,7 +111,7 @@ Let's draw the page. All the functions in Tyrian are encouraged to be pure, whic

The `view` takes the latest immutable (read-only) model, and produces some HTML in the form of `Html[Msg]`.

```scala mdoc:silent
```scala mdoc:js:compile-only
def view(model: Model): Html[Msg] =
div(
button("-"),
Expand All @@ -130,30 +130,28 @@ div(id := "my container")(...)

Of course a button isn't much use unless it does something, and what we can do is emit an event, called a message, when the button is clicked. For that we need to declare our message type which we'll do as a simple enum that represents the two actions we want to perform:

```scala mdoc:silent
```scala mdoc:js:shared
enum Msg:
case Increment, Decrement
```

...and add our click events:

```scala mdoc:reset:invisible
```scala mdoc:js:compile-only
import tyrian.Html.*
import tyrian.*
import cats.effect.IO

type Model = Int
enum Msg:
case Increment, Decrement
```

```scala mdoc:silent
def view(model: Model): Html[Msg] =
div(
button(onClick(Msg.Decrement))("-"),
div(model.toString),
button(onClick(Msg.Increment))("+")
)
def view(model: Model): Html[Msg] =
div(
button(onClick(Msg.Decrement))("-"),
div(model.toString),
button(onClick(Msg.Increment))("+")
)
```

> Note the return type of view is `Html[Msg]`. This is because unlike normal JavaScript, the `onClick` is not directly instigating a normal callback, the HTML elements are mapped through and produce messages as values that are passed back to Tyrian.
Expand All @@ -162,7 +160,7 @@ enum Msg:

The final thing we need to do is react to the messages the view is sending, as follows:

```scala mdoc:silent
```scala mdoc:js:compile-only
def update(msg: Msg, model: Model): (Model, Cmd[IO, Msg]) =
msg match
case Msg.Increment => (model + 1, Cmd.Empty)
Expand Down
2 changes: 1 addition & 1 deletion project/plugins.sbt
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
addSbtPlugin("org.xerial.sbt" %% "sbt-sonatype" % "3.9.7")
addSbtPlugin("com.jsuereth" %% "sbt-pgp" % "2.0.1")
addSbtPlugin("org.portable-scala" % "sbt-scalajs-crossproject" % "1.1.0")
addSbtPlugin("org.scala-js" % "sbt-scalajs" % "1.9.0")
addSbtPlugin("org.scala-js" % "sbt-scalajs" % "1.8.0")
addSbtPlugin("io.github.davidgregory084" % "sbt-tpolecat" % "0.1.20")
addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.9.31")
addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.3.2")
Expand Down