docs.scala-lang
docs.scala-lang copied to clipboard
scala
Animate operations of the Scala collections
This is a port of https://github.com/scala/collection-strawman/issues/155.
The idea is to have something similar to https://superruzafa.github.io/visual-scala-reference/index.html#groupby for the Scala collections in Scala 2.13, but maybe built with something more modern like https://github.com/stanch/reftree that is both Scala and Scala.js compatible.
There are lots of ideas and points in the linked ticket. I personally think this would make for an excellent contribution. What would need to be done is to start creating a prototype of it, and then we would find a way to integrate this with Scaladoc.
Another reference https://www.reddit.com/r/scala/comments/7cb01u/help_me_find_a_scala_collections_api_cheat_sheet/
I've created the ReactiveX marbles using scalatags and SVG: https://scalafiddle.io/sf/ITGhzIm/1
ScalaFiddle could be used inside the docs directly. Otherwise given PR#930 the scalatags could be used directly.
@Lasering That would be an approach! I think that it would be better though if we generate static images instead on every merge. I think that the benefits of this approach are two: we are independent from Scalafiddle's availability and no JS is used (reducing the overhead when rendering the browser).
Fair enough. It would especially hinder mobile browsers.
I suggested it because I was thinking about a REPL where the results would be rendered as SVG images. This way we could show what the method would do, and at the same time allow to user to play with it.
This way we could show what the method would do, and at the same time allow to user to play with it.
Do you mean that you'd like to generate svg images not only for one operation, but for several chained operations?
FWIW, I think we could render SVG images statically, but this approach would definitely not allow users to play with it. However, if we do it right I think we could make the Scala code that generates the images Scala.js compatible and then allow your use case in platforms like Scalafiddle or Scala.js.
Do you mean that you'd like to generate svg images not only for one operation, but for several chained operations?
In practice yes, but only if the user interacted with the Fiddle and created that chain of operations.
The idea is: the scaladocs of each relevant collections method has an embedded ScalaFiddle (imagine substituting the images ReactiveX has with ScalaFiddle). This ScalaFiddle implements a very simple REPL, if an expression evaluated by the REPL has an instance of some typeclass DrawableAsSVG then draw the result instead of showing it normally. Example of an interaction:
scala>List(1, 2, 3)
res0: List[Int] = List(1, 2, 3) // Normal representation because Ints have no DrawableAsSVG
scala>res0.map(i => Marble(sides = 3 + i))
<<an SVG representation of the result of map would be shown, something like my fiddle above>>
You could of course chain a lot of operations and the resulting collection would be shown. But that would only be useful if the user could interact with the REPL and input those expressions.
The REPL would come preloaded with the best interaction possible to showcase the current operation. For example the filter method could come with the following:
scala> List(Triangule, Square, Pentagon, Hexagon)
<<SVG representation of res0>>
scala> res0.filter(_.sides <= 4)
<<SVG representation of res0 without Pentagon and Hexagon>>
The idea of using marbles is just an idea. I've suggested it because, in my opinion, is very good at conveying the necessary information, and engaging the user. If a better option is found we could use it instead of the Marbles.
The code I made is using scalatags so its compatible with Scalafiddle and Scala.js.
As you mentioned this idea as some disadvantages, we would be tied to the availability of ScalaFiddle and the documentation would be an heavy page to load. However I still thing the general idea is good, as we could use the code just to generate the images and then inline them just like ReactiveX does.
Hello guys. I would like to propose another option. This is going to be somewhere half way between a static image representing the exploded diagram of a Scala collection operation and live interactive animations on Scalafiddle. GIFs: Jorge suggestion was very good. Use something with scala.js but still, we need something to be animated. Now I know you lose interactivity but on a documentation page that is kind of the expected behavior anyway. So my proposal is to use something like scala.js, reftree and a library that would capture the animation and generate a GIF out of it. What do you guys think?
Use something with scala.js but still, we need something to be animated. Now I know you lose interactivity but on a documentation page that is kind of the expected behavior anyway. So my proposal is to use something like scala.js, reftree and a library that would capture the animation and generate a GIF out of it. What do you guys think?
That sounds like the best approach. It's flexible enough that we can create something more dynamic on top of it while still being static for the documentation, my 👍
Ok, so now I have a project that generates animated diagrams in the gif format. For now I generate them in a Scala project since Scala.js is not an option for now. The scala documentation site uses the static pages generator and there is no scala project wrapping that (for now?). So I have a local project doing the heavy work of the diagram generation and we can discuss later how we glue things. To keep working on a simple draft and have some meaningful diagrams I need to know what to actually display? Let me pick the immutable queue collection as an example. Should we:
- Generate a diagram enqueing and dequeuing to show the mechanism behind (one diagram)?
- Generate a diagram for enqueing and one separate for dequeing (multiple key diagrams)? So I need an exact list of what to generate. If the diagram will be included in scaladoc block code above the class description then this a diagram per class. If we want to include in every key class methods a simple diagram, then this a diagram for each key functionality. So, any suggestions?
If we want to include in every key class methods a simple diagram, then this a diagram for each key functionality
I would show a diagram per method in a similar fashion as the following link https://superruzafa.github.io/visual-scala-reference/index.html#groupby. We can start by doing this in a dummy static website for a specific example, like the immutable queue collection, and then talk about integrating that into scaladoc down the road.
I wouldn't worry about Scala.js actually, since all of this is likely to be run within scaladoc (or a tool we integrate with it) running on the JVM. Having the possibility of generating it with scala.js is great if someone wants to pick the project up and generate these diagrams on the fly, but it's not a strict requirement -- we only care about static pages.
@jvican JavaScript can be used to implement interactive diagrams like in ReactiveX docs.
@codingvlad That’s really nice from you to initiate this effort! I would say like @jvican that we have no precise expectation, any improvement to the current state of the docs is good to have! I’m just a little bit worried about the maintenance part: who is going to maintain these diagrams and to make sure that they are consistently provided for each operation?
@julienrf Thank you. I do not know who will manage the process of indexing, reviewing and all that stuff. I know building the diagrams is quite some work (using any of the approaches). You have to know the framework (in my example rftree) and then build the best representation for every case. That work is what I can do. But maybe it would be a good idea that the scala center gets involved and reviews my work on the diagrams. So maybe a project under scalacenter on github to which I commit and you guys review is a good workflow. Anyway, I will continue working on this using rftree since the javascript approach needs updating more core stuff in your build of the docs. My target is to have a mirror folder structure of the collection folder in scala but with generated diagrams inside. This way, they are easy to find. The location of a diagram should be that of the package name + class name + method name. (i.e if someone would like to add a diagram on the immutable.Queue dequeue method, they would find a diagram in the folder collection.immutable.queue named dequeue.gif.)