Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    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.
    Chris Stewart
    @Christewart
    It could
    Chris Stewart
    @Christewart
    Does unidoc even require it's own brancy anymore? I haven't looked at this in forever
    It seems that docusraus (which mdoc uses) is the thing publishing to the gh pages branch? https://github.com/bitcoin-s/bitcoin-s/tree/gh-pages
    Nishant Vishwakarma
    @nishantv12

    I was trying to explore mdoc in a sample project following the documentation. I have added the plugin in plugins.sbt and created two projects in build.sbt where docuemntation project depends on my root project as given in the documentation. However, when I run docs/mdoc I get error for dependency resolution as mdoc is looking for 2.12 version of the project but I am using 2.13.

    addSbtPlugin("org.scalameta" %% "sbt-mdoc" % "2.2.21")
    lazy val `sample-project` = project
      .in(file("."))
      .settings(
          name := "sample-project",
          version := "0.1",
          scalaVersion := "2.13.3"
      )
    lazy val docs = project       // new documentation project
      .in(file("myproject-docs")) // important: it must not be docs/
      .settings(
        mdocVariables := Map("VERSION" -> version.value, "SCALA_VERSION" -> "2.13.3")
      )
      .dependsOn(`sample-project`)
      .enablePlugins(MdocPlugin)

    What am I missing?

    Anton Sviridov
    @velvetbaldmime:matrix.org
    [m]
    SBT will set it to 2.12 by default
    I think you need to explicitly set scalaVersion to 2.13.13 on the docs project as well