scalameta/mdoc

Typechecked markdown documentation for Scala

Andrew Valencik

@valencik

Is the example report broken in the docs? https://scalameta.org/munit/docs/reports.html I'm just seeing some ending table tags

Ólafur Páll Geirsson

@olafurpg

@valencik I opened scalameta/munit#305 to remove that page

You can browse the older docs https://javadoc.io/doc/org.scalameta/munit-docs_2.12/0.7.21/munit/docs/reports.html

Anton Sviridov

@keynmol

I've started fleshing out a repro for @raquo's issue here: scalameta/mdoc#455

Sadly the naive approach doesn't seem to work, tests are still passing

I have another approach of intercepting a CLI command one of my tool makes and trying to make it match the reproducible in the issue.

Nikita Gazarov

@raquo

Thanks, is there some way I could make my own repro branch even smaller / more useful? mdoc internals are beyond me, but I could... rip out some more stuff from my branch if that helps?

Anton Sviridov

@keynmol

I think the closest we will get is to get a CLI reproducible: https://scalameta.org/mdoc/docs/js.html#command-line

Admittedly, it's quite hairy and that's why I wanted to reproduce it in tests first.

Is this blocking you from upgrading laminar to 1.3x (asking because I thought you wanted to postpone that)

Nikita Gazarov

@raquo

It's technically blocking me from releasing Laminar 0.12.0 because its dependencies require 1.3.0, but we can re-release the dependencies based on 1.1.0. Since this issue appears to be complicated, I think we will end up doing that to avoid creating an urgency for the fix.

Anton Sviridov

@keynmol

Ok, so by invoking CLI directly (well, through my tool) I seem to be able to compile this file with laminar being a dependency

3 replies

(mdoc 2.12.16, SJS 1.3.0)

So next step is reproducing those peculiar files

Anton Sviridov

@keynmol

a-ha! I just got the error. Reduced it down to a single java -classpath command!

It's full of refs to my own folders, but from here I can make it into a coursier-only reproducible.

Nikita Gazarov

@raquo

:tada: Nice

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

Where communities thrive

People

Repo info

Activity