Refactor: Add documentation for the Scastie configuration

[Dedelweiss]

I have noticed that in most Scala projects using Scaladoc with snippets. When snippets were using external libraries, these did not work. Example:

Planned or just lack of interest to look into it further, the question remains "How to fix it?".
So I noticed that a -scastie-configuration flag was present but as discussed in Issue #16220 on Dotty, nothing explains how to use it or anything.
So when testing some things, I noticed that it was behaving like the "Add Extra Sbt Configuration" input of the Scastie web application.

And as soon as I added the following piece of code, the snippet worked as it should.

So the goal to this PR is to add some documentation about -scastie-configuration flag so the users can make the best use of Scastie.

Fixes: scala/scala3#16220

[julienrf]

Thank you for the investigation and the fix! Indeed, documenting this option seems important. There is something that is still unclear to me: how do we enable the “Scastie button”?

[Dedelweiss]

Thank you for the investigation and the fix! Indeed, documenting this option seems important. There is something that is still unclear to me: how do we enable the “Scastie button”?

Hello, If I'm not mistaken and you are talking about the "play" button. It seems to me that it is activated when you put the sc:compile part. I can add it in the documentation but does it fit in the flags part or would a dedicated page be better?

[julienrf]

Thank you for the improvement. I think at some point we should also document better the whole feature that adds this “play” button, but that could be done in a separate PR.

[Dedelweiss]

Thank you for the improvement. I think at some point we should also document better the whole feature that adds this “play” button, but that could be done in a separate PR.

Thank you, okay sure, I can do it if it's not a problem. I was thinking of either a page or a part here dedicated to the explanation of the possible parameters after the ```of a blockquote. Or else a page dedicated to the explanation of Scastie and its possible uses, I haven't found much of a page talking about it on docs.scala-lang (except briefly if I'm not mistaken).

[julienrf]

That would be great if you can do it! 🙏

Is that feature related to the -snippet-compiler:compile option described here? If yes, I think the documentation could go to that page (maybe rename it to “Embedding code snippets” to make it more general, and make subsections like “snippets checking” and “interactive snippets”).

[Dedelweiss]

Ho sorry, I will see if I have any improvements to suggest but I notice the documentation is already there. Indeed, if I'm not mistaken, the "Getting Started" part explains how to activate all the snippets and then the "Advanced configuration" part explains how to individually activate a snippet as I did with sc:compile. I can even add an example for sc:compile and sc:nocompile because it is only the case for sc:fail in features overview.