Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    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]
    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
    Matt Dziuban
    @mrdziuban
    added an issue here: scalameta/mdoc#479
    Odomontois
    @Odomontois

    Hi, we have some strange behaviour during "unidoc", it's unrelated to mdoc I suppose, but I have no idea where to ask.
    We have strange behaviour during our docs construction, seems like during compilation some old version of dependencies, such as cats, and cats-effect are used.
    For instance, during doc generation for this file
    https://github.com/tofu-tf/tofu/blob/master/concurrent/src/main/scala/tofu/concurrent/MakeMVar.scala#L24:L24
    error

    type mismatch;
    [error]  found   : I[cats.effect.concurrent.MVar[F,A]]
    [error]  required: I[cats.effect.concurrent.MVar2[F,A]]

    produced

    and numerous others when it seems like doc compilation refers to older version of dependencies
    Have someone seen something like that?
    Tomasz Godzik
    @tgodzik
    @Odomontois I am not familiar with unidoc, how does it use mdoc? is it this one: https://github.com/sbt/sbt-unidoc ?
    maybe sbt/sbt channel might be better to ask
    Mike Limansky
    @limansky
    Hi. I've started to create documentation using mdoc and Docusaurus and cannot get what is the proper way to handle static assets in documentation? I'd like to have images together with markdown files in the docs folder, but as I see Docusaurus handle only static assets in website/static. Is there some common way to work with images?
    Ólafur Páll Geirsson
    @olafurpg
    @limansky i generally avoid committing image files into the git repo. It typically works better IME to reference GitHub URLs.
    images often make the repo large to clone, and once you have committed the image it’s part of the history forever even after the docs stop referencing the image
    Mike Limansky
    @limansky
    @olafurpg thanks for reply. I got your point, but on the other hand, committing images keeps history consistent, and it is always possible to restore the site on some commit. Also, I don't think we'll have a lot of images, that's why I think it would be better to keep all in one place. The only solution I came up with (but not implemented yet), is to copy assets via sbt task to a subfolder of website/static which have to be added to .gitignore. I just asking if there something better than this, or some built-in code for it.
    Ólafur Páll Geirsson
    @olafurpg
    @limansky can you place the images directly under website/static?
    Alternatively, mdoc does support multiple in/out pair of directories.
    Mike Limansky
    @limansky
    Well, I'd like to separate content and template.
    Ólafur Páll Geirsson
    @olafurpg
    It can only be used from the sbt plugin by configuring extra cli arguments. You pass in extra —in and —out flags
    But not sure how that can help
    Mike Limansky
    @limansky
    ok :)
    Chris Stewart
    @Christewart
    has anyone had problems with mdoc and accumulating ever growing git history? Our repo takes forever to clone because it apperas things keep getting added to the docs/ folder on every merge
    1 reply
    Anton Sviridov
    @velvetbaldmime:matrix.org
    [m]
    How's your build set up? I never check in the results of mdoc generation
    Anton Sviridov
    @velvetbaldmime:matrix.org
    [m]
    mdoc itself doesn't generate html files, are you sure it's not unidoc's API files?
    also - I'm guessing you're referring to gh-pages branch?
    because mdoc doesn't check anything in either.