Migrate readme project to another docs framework
armanbilge opened this issue · 7 comments
The readme project currently depends on scalatex which unfortunately no longer seems to be maintained. Thus the docs should migrate to another framework, e.g. mdoc supports Scala.js although it's not entirely clear to me if this is introducing a circular dependency or not.
Just thinking out loud that it may be easier to just make the readme a static github md file and remove interactivity and other visuals. Then just add the readme as the main readme.md for the repo. Maybe add some critical content if someone identifies it is missing. At least reduces complexity for awhile.
Yeah, that can be our back-up plan if things break before someone gets around to this. For now still seems to be working!
Just a quick note—I had a go with mdoc.js in http4s/http4s-dom#29 and I had an excellent experience. I think it is very viable to port the current docs, and would be a fun project for a motivated individual :)
I'm marking this as "good first issue": I think the trickiest part would be the build setup, which I can help with if someone is interested to work on this. From there it should be pretty straightforward!
Finally, a note on the circular dependency: well, that seems unavoidable :) (scalatex also technically has a circular dependency to sjs-dom v1!). However, it's worth noting that the mdoc.js dependency is fairly uncoupled in the sense that it doesn't need sjs-dom to build (since its just doing source-generation) nor does it put sjs-dom on the classpath automatically. Their sjs-dom dependency is purely for testing and generating their own docs.
At least a couple issues have reported issues running prePR due to weird scalatex errors. So this is even more incentive to change. Edit: aha, it is lihaoyi/Scalatex#69.
[info] compiling 2 Scala sources to C:\Users\mario\code\src\github.com\mabasic\scala-js-dom\readme\target\scala-2.12\classes ...
[error] C:\Users\mario\code\src\github.com\mabasic\scala-js-dom\readme\Index.scalatex:43:6: type mismatch;
[error] found : scalatex.site.Section.Proxy
[error] required: scalatags.Text.all.Frag
[error] (which expands to) scalatags.generic.Frag[scalatags.text.Builder,String]
[error] @sect{scala-js-dom}
[error] ^
[error] one error found
[error] (readme / Compile / compileIncremental) Compilation failed
[error] Total time: 136 s (02:16), completed 31.08.2022. 22:51:29
What about just using scaladoc 3? https://docs.scala-lang.org/scala3/scaladoc.html
@zetashift does Scaladoc 3 support Scala.js? I.e. can it be used to make interactive in-browser snippets?
That's a good one, it has runnable snippets, but I can't find anything about it for interative snippets :S