search

scalameta / mdoc

Typechecked markdown documentation for Scala
https://scalameta.org/mdoc/
Apache License 2.0
394 stars 80 forks source link

Documenting Scala 2/3 approaches #835

Open adamnfish opened 7 months ago

adamnfish commented 7 months ago

For libraries that use advanced Scala features (most commonly typeclass derivation) the approach is likely to differ for users on Scala 2.x / vs 3.x. Documenting both approaches is important while both Scala versions are supported, which is likely to be the case for some time.

Is this possible now? I haven't been able to find any settings that would allow code blocks to use different compilers, and indeed mdoc's "program semantics" approach implies this might be a non-goal.

If it isn't possible, perhaps others have examples or recommendations for how best to address this Scala 2/3 split?

Thank you!

tgodzik commented 7 months ago

Thanks for raising this! I think that looks like a really needed feature, but currently this is not possible. However, while not easy by all means, It should probably be possible to add a custom tag that would manually invoke mdoc as a library with two different Scala versions. Like in https://scalameta.org/mdoc/docs/modifiers.html#stringmodifier

You could take a look at how Metals does it for worksheets in https://github.com/scalameta/metals/blob/46957a94f1f3ad57990ea7f7b09bf6ff8f38ae9a/metals/src/main/scala/scala/meta/internal/worksheets/WorksheetProvider.scala#L405

Though the API might be less than ideal for you here. It would probably be great to have that implemented internally in Mdoc, but unfortunately this is not in the plans currently.