scalameta/mdoc

Typechecked markdown documentation for Scala

Ólafur Páll Geirsson

@olafurpg

Getting the tests to pass should be a lot more fun than tweaking the build settings

Julien Truffaut

@julien-truffaut

Thanks for the pointers, I doubt I will have the bandwith to look into it but I will definitely follow it closely.

Anton Sviridov

@keynmol

a lot more fun

"fun"... you use that word :D

I didn't know you already started that - will try to take a look and see what needs to be fixed

Julien Truffaut

@julien-truffaut

Which version of docusorus is supported by mdoc? v1, v2, both?

Ólafur Páll Geirsson

@olafurpg

I think both work, unless they changed the commands to build/deploy sites

@keynmol “more” fun, editing build.sbt and reloading a hundred times is a low bar

Julien Truffaut

@julien-truffaut

Cheers, if by any chance someone managed to set up a docusorus v2 with mdoc, I would be super interested to have a look. I am completely useless with these sort of things.

Ólafur Páll Geirsson

@olafurpg

https://v2.docusaurus.io/docs/migration/manual#update-references-to-the-build-directory

If you are deploying to GitHub pages, make sure to run yarn deploy instead of yarn publish-gh-pages script.

Looks like they changed the deployment commands so sbt docusaurusPublishGithubSomethingCommand won't work

sbt-docusaurus is only a thin layer on top of docusaurus itself

the Docusaurus docs are the best place to look for information

Use Docusaurus v2 if:
✅ You want a single-page application (SPA) with client-side routing

Not sure I personally want this

Docusaurus v1 works fine IMO, I just wish the search was local so that it worked on offline copies of old versions

Jad Hamza

@jad-hamza

Hi all,
I'm having an issue moving from tut to mdoc on a project using Scala 2.12.8:
I tried: addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.2.18") and addSbtPlugin("org.scalameta" % "sbt-mdoc_2.12" % "2.2.18") but both failed:

The first one looks for:
https://repo1.maven.org/maven2/org/scalameta/mdoc-runtime_2.12.8/2.2.18/mdoc-runtime_2.12.8-2.2.18.pom
and the second one looks for:
https://repo1.maven.org/maven2/org/scalameta/sbt-mdoc_2.12_2.12_1.0/2.2.18/sbt-mdoc_2.12-2.2.18.pom maybe because of coursier/coursier#1950
(while the correct URL is https://repo1.maven.org/maven2/org/scalameta/mdoc-runtime_2.12/2.2.18/mdoc-runtime_2.12-2.2.18.pom)

Ólafur Páll Geirsson

@olafurpg

@tgodzik that error message looks related to the recent changes around full/binary versions. What is the recommendation for users on 2.12.8?

@jad-hamza what happens if you upgrade to the latest 2.12.x release?

(Scala version)

Tomasz Godzik

@tgodzik

yeah, that's the error - I haven't yet figured out how to solve it. Best would probably be on the coursier side, there are really 3 workarounds to that issue:

updated to 2.12.12/13
turn off coursier
stay on earlier version of mdoc v2.2.15

Jad Hamza

@jad-hamza

We were able to upgrade Scala to 2.12.13, so it's all good now, thanks!

Anton Sviridov

@velvetbaldmime:matrix.org

[m]

This message was deleted

1 reply

Grigory

@pomadchin

Hi everyone!
Starting the sbt-mdoc plugin version v2.2.15 we’re getting the following error in the project:

docs/mdoc
[warn] There may be incompatibilities among your library dependencies; run 'evicted' to see detailed eviction warnings.
[error] Modules were resolved with conflicting cross-version suffixes in ProjectRef(uri("file:/Users/daunnc/subversions/git/github/pomadchin/franklin/"), "docs"):
[error]    org.scalameta:mdoc-runtime _2.12.12, _2.12
[error]    org.scalameta:mdoc _2.12.12, _2.12
[error] stack trace is suppressed; run last docs / update for the full output
[error] (docs / update) Conflicting cross-version suffixes in: org.scalameta:mdoc-runtime, org.scalameta:mdoc
[error] Total time: 3 s, completed Mar 9, 2021 1:44:36 PM

The project Scala version is 2.12.12 / 2.12.13

Are there any pointers towards this issue resolution?

Rollback to 2.2.14 plugin version works

Tomasz Godzik

@tgodzik

@pomadchin we had to do some changes to support Scala 2.12.13 and I think it's not working 100% for Scala versions < 2.12.12

could you report an issue maybe?

Grigory

@pomadchin

@tgodzik :+1:

Jack Koenig

@jackkoenig

I'm pretty sure the answer to this question is "no", but is it possible to have multiple mdoc code blocks that are combined into a single class or function definition? I work on APIs where everything is inside of classes but it would be nice to show snippets of code without having to show the full wrapping class each time.

1 reply

Ólafur Páll Geirsson

@olafurpg

@jackkoenig can you give a concrete example?

Jack Koenig

@jackkoenig

So I work on a DSL where most things need to live inside a class, and error detection usually needs a particular incantation to run the block of code. I'm thinking something like:

```scala mdoc:invisible:start
import chisel3._
class MyModule extends Module {
  val a, b = IO(Input(UInt(8.W)))
  val en = IO(Input(Bool()))
  val out = IO(Output(UInt(8.W)))
```
You can define a mux like so:
```scala mdoc:silent
out := Mux(en, a, b)
```
```scala mdoc:invisible:end
}
// This runs our own runtime checks
chisel3.stage.ChiselStage.emitVerilog(new MyModule)
```

And what I want to render in the output markdown:

You can define a mux like so:
```scala
out := Mux(en, a, b)
```

For purposes of the example, the signals involved (out, en, a, and b) don't really matter. And all of the boilerplate really distracts from the example I'm trying to show

I could probably write my own modifier using comments or something to strip lines, something like:

You can define a mux like so:
```scala mdoc:prune
import chisel3._ // prune
class MyModule extends Module { // prune
  val a, b = IO(Input(UInt(8.W))) // prune
  val en = IO(Input(Bool())) // prune
  val out = IO(Output(UInt(8.W))) // prune
out := Mux(en, a, b)
} // prune 
chisel3.stage.ChiselStage.emitVerilog(new MyModule) // prune
```

And just have it strip each line with the prune comment

Jack Koenig

@jackkoenig

And the behavior I want on the first example is that the 3 mdoc blocks from start to end are compiled together. I don't know if it really makes sense, the custom modifier doing some pruning after the fact is probably just what I should do...

Ólafur Páll Geirsson

@olafurpg

@jackkoenig is it possible to wildcard import from MyModule? I have used that trick to for example document how to write MUnit tests.

Currently, every code fence needs to parse independently due to implementation details

I estimate it would require a large internal refactoring to support the example above.

Jack Koenig

@jackkoenig

Wildcard import is a neat trick, I don't think it'll work for my particular case (due to implementation details of my library, Chisel), but I'll keep it in mind because I can see it coming in handy. I could use inheritance to get it down a bit, and maybe I should do the custom modifier idea as well.

I totally get why this would be a difficult thing to support, I appreciate your responses!

Matt Dziuban

@mrdziuban

hi all, is there a way to have a PreModifier that then hands the resulting code off to the regular scala mdoc modifier to be compiled/evaluated?

Ólafur Páll Geirsson

@olafurpg

@mrdziuban that’s a good question. I dont think so. Can you give an example how you would use that?

i’m curious how positions of compile errors inside the generated code should be mapped in that case

mdoc already has one layer of syntactic transforms, it should be technically possible to add expose a hook for one more transform

Matt Dziuban

@mrdziuban

@olafurpg I'm trying to cross build documentation for multiple versions of a library dependency (http4s) so I'd like to do something like this

```scala mdoc:http4s
import org.http4s.Uri

val uri = Uri(path = "/my-path") // v0.21
val uri = Uri(path = Uri.Path.unsafeFromString("/my-path")) // v1.0.0-M20
```

and then have the http4s modifier parse the code and only keep the lines with a comment specifying the current version that I'm building for

Ólafur Páll Geirsson

@olafurpg

@mrdziuban feel free to open an issue explaining this use-case

Matt Dziuban

@mrdziuban

:+1: will do, thanks

Ólafur Páll Geirsson

@olafurpg

I think it's totally possible to support something like this. I can't think of a workaround at the moment

Anton Sviridov

@velvetbaldmime:matrix.org

[m]

image.png

I had a similar issue but with post(?) modifier - I wanted to just evaluate the last value and pass through to other modifiers (i.e. silent) but that's not possible atm:

Instead I made io-silent which combines the behaviours, which is not ideal

Where communities thrive

People

Repo info

Activity