scalameta/mdoc

Typechecked markdown documentation for Scala

Anton Sviridov

@keynmol

Even better - here's a single bash script (with coursier) reproduction on CI :) https://github.com/keynmol/mdoc-scalajs-problem/runs/1834922392?check_suite_focus=true#step:4:22

not sure it's possible to go even more minimal

Anton Sviridov

@keynmol

Ok, at this point I need to disappear, given the time, but now I have something where I can vary mdoc version to see if I can fix this. (I've also confirmed 2.2.11 -> 2.2.12 jump being the regression).

Sorry that that you hit this issue, it sucks that I can't help more :-/

Nikita Gazarov

@raquo

This is great progress, thanks!

Ólafur Páll Geirsson

@olafurpg

@keynmol I think the CI release process only triggers when you push a git tag

I have a git release 1.2.4 script like this

❯ cat `which git-release`
set -eux
version=$1
git tag -af "v$version" -m "v$version" && git push -f origin v$version

the --force flag is options, but I use it by default since I occasionally need to push a new tag to trigger a CI job

Anton Sviridov

@keynmol

so weird that it shows a tag "pushed" 8 hours ago - I usually tag projects through UI as well

I'll re-push the tag then

Anton Sviridov

@keynmol

ok it's building now :+1: I wonder if it's because of release-drafter? in another project Github Actions does recognise the new releases as pushes of new tags

Ólafur Páll Geirsson

@olafurpg

I think the release yaml config in the mdoc repo doesnt run on the “release” event. Changing that should fix it.

Julien Truffaut

@julien-truffaut

Hi all, is there a way to produce to produce a docusaurus website with mdoc with most pages in two versions: one for scala 2.13 and one for scala 3

Anton Sviridov

@keynmol

I don't think mdoc supports building scala3 markdowns yet? It was depending on Scalameta, I think

Julien Truffaut

@julien-truffaut

ah thanks for letting me know

Anton Sviridov

@keynmol

I'd suggest verifying this, but this is still there :) scalameta/mdoc#414

Ólafur Páll Geirsson

@olafurpg

@julien-truffaut at the moment there's no support to generated mixed-version docs. It would be a nice feature

you can use crossScalaVersions to cross-build the docs sbt project against multiple versions, but that would give you independent copies of the entire website

scala 3 is not yet supported for processing markdown files

The PR scalameta/mdoc#443 gets the Scala 3 build compiling but the tests are still failing

I probably won't complete that PR myself in the near future, but it might be helpful for someone else who would like look into Scala 3 support.

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)
```

Where communities thrive

People

Repo info

Activity