Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
    Ólafur Páll Geirsson
    @olafurpg
    @philbertwallace_twitter What is the biggest blocker for you?
    I created mdoc primarily to speed up existing tut documentation so was designed mostly for that use case.
    mdoc goes to pretty great lengths to preserve line numbers from the markdown source, but it makes editing easier
    philbert
    @philbertwallace_twitter
    @olafurpg yah, that makes total sense! Biggest blocker for me is that I'm looking for a tool that I can basically start from scratch in almost a classical "literate programming" style -- ie: starting from a completely blank project and building up essentially what will become a programming book where the reader of the book almost by definition is a "user" of the code
    hope that makes sense -- essentially i'd really like something like the sbt-scaliterate plugin but when the compiler gives me an error i'd like to be able to easily find it in my document (which might be large with lots of code fences). But what I really do like about the sbt-scaliterate plugin is that it allows me to interleave packages and such (ie: in one code fence add an object to a package and then in another, later down in the document, add another object to the same package)
    Ólafur Páll Geirsson
    @olafurpg
    So you need to evaluate / run code fences @philbertwallace_twitter ?
    philbert
    @philbertwallace_twitter
    yes, but specifically i need to be able to declare a package within a code fence earlier in the document, add some objects, traits and whatnot to that package, then continue on with my writing, and then open another code fence and, perhaps, add more objects traits to the same package or, perhaps, add some objects/traits to a new package. Essentially what I'm attempting to write is more than a "how to use my library" tutorial...instead it's more of a "let's build this library together" book ;-)
    hope that provides a better usecase
    in other words, the document i'm trying to write is also the same document that (would) contain the code for the library/app/concept that i'm attempting to teach/elucidate for people
    of course, one thought I had was to just try to do this in one giant .scala file as that way i'll still get the IDE advantages, but then i lose the neat stuff that mdocs provides such as demonstrating when certain things will not compile and such
    philbert
    @philbertwallace_twitter
    /**
      Ok, let's get going. This is going to be a really long file, but let's we do!
      */
    package pkgA {
      object obj1 {
        def hello = "hello world! from object 1"
      }
    }
    
    /**
      * Ok great, we have a package with an object in it. Now let's add another object to this same package!!
      */
    
    package pkgA {
      object obj2 {
        def hello = "hello from object 2"
      }
    }
    
    /**
      * ok neat, now let's create another package, package C, with an object in it called objC. From within this
      * package we can import pkgA and it's objects and use them. Wow!
      */
    
    package pkgC {
      import pkgA._
    
      object objC {
        def whatDoesObj2Say = obj2.hello
      }
    }
    The above is an example of sort of the style i'm going for. My (perhaps naive) thought is that by sticking to only a finally tagless style coding i can get a pretty long way by simply building up the app/library bit by bit in a linear (and literate) fashion. Albeit, I'll end up with a massive scala file at the end of it lol.
    Ólafur Páll Geirsson
    @olafurpg
    If I understand correctly the main issue you face is the inability to declare packages?
    Would it be acceptable to use objects as namespaces instead?
    philbert
    @philbertwallace_twitter
    @olafurpg hi, sorry of my example was not very clear. The primary reason why being able to do packages is interesting isn't so much the packages themselves but the fact that you can "add things to" a package as you move along in the writing of the document/program. This isn't possible with objects, at least not any way that I know how. Once an object has been declared we want, later in the document, add more methods to it, whereas with packages we can in fact add more objects. Hope that brings some more clarity as to my reasoning?
    Ólafur Páll Geirsson
    @olafurpg
    @philbertwallace_twitter makes sense, thanks for the explanation
    How would you expect the following document to work?
    
    ```scala mdoc
    package a
    class A
    ```
    
    ```scala mdoc
    package b
    class A
    ```
    
    ```scala mdoc
    new a.A
    new a.B
    ```
    would it be an acceptable solution to have a modifier like mdoc:file (or mdoc:package, name up for debate) that would compile that code fence in a separate file without instrumentation?
    Ólafur Páll Geirsson
    @olafurpg
    it would be be a normal file that doesn't evaluate, but you can reference it from the other code fences
    it would require some effort to recover compile errors but I think it's doable
    philbert
    @philbertwallace_twitter
    @olafurpg i'm trying to think through the example you gave. I'm not quite sure I'm following what your proposing with the mdoc:file modifier.
    philbert
    @philbertwallace_twitter
    part of the challenge could simply be on my end (not knowing precisely what it is that I'm after but only merely having a feeling for it at the moment) ;)
    Ólafur Páll Geirsson
    @olafurpg
    I played around with vscode so get diagnostics + live preview into the editor and it came out quite nicely olafurpg/mdoc#104
    Viktor Rudebeck
    @vlovgr
    @olafurpg do you know of an easy way to add scaladoc to a sbt-docusaurus site? (I haven't looked at it yet, so just wondering if you already know how.)
    Ólafur Páll Geirsson
    @olafurpg
    @vlovgr It's a good question, I haven't looked into it but it should be doable with a bit of sbt voodoo
    I would personally want to have a similar tool as scaladoc that generates API/reference directly within the docusaurus site.
    if you want to take a stab at integrating scaladoc however, I would look at the docusaurusCreateSite command https://github.com/olafurpg/sbt-docusaurus/blob/bfbe5d64bf71c80fda194f105f97bb016e99c209/plugin/src/main/scala/sbtdocusaurus/DocusaurusPlugin.scala#L99-L107
    we could copy over the scaladocs at that point
    Viktor Rudebeck
    @vlovgr
    Having scaladoc output on the site, with a link to it, is a good first step. But I agree something more integrated would be fantastic. I'm going to setup sbt-docusaurus for a new project, and then take a look at getting scaladoc in there once that's done. Thanks! :)
    Ólafur Páll Geirsson
    @olafurpg
    note that sbt-docusaurus overrides the doc task, which I've considered reverting
    sbt-docusaurus doesn't really do so much, but one thing is that it can generate a static docusaurus site with relativized links so it can be hosted on static.javadoc.io
    I never ended up using that feature much however...
    Viktor Rudebeck
    @vlovgr
    I see. I think javadoc doesn't support unified scaladoc though right? It's not unusual to have > 1 module in projects, and it's quite nice to have all documentation in one place.
    Ólafur Páll Geirsson
    @olafurpg
    there's sbt-unidoc
    I don't have much experience with it but it should be able to unify docs in multi-module builds
    Viktor Rudebeck
    @vlovgr
    Yes, that's what I use normally. But in published artifacts, I normally don't have the unified docs.
    Ólafur Páll Geirsson
    @olafurpg
    the unified scaladoc can be enabled only for the docs project
    which you don't have to publish
    Viktor Rudebeck
    @vlovgr
    Yes, that's what I do here: https://cir.is/api/
    Viktor Rudebeck
    @vlovgr
    @olafurpg my first sbt-docusaurus site is now up! :tada: https://ovotech.github.io/fs2-kafka/
    Viktor Rudebeck
    @vlovgr
    The only thing I missed was not being able to include markdown (mdoc output) in pages. But apparently, that has been done for docusaurus 2.0.
    Ólafur Páll Geirsson
    @olafurpg
    @vlovgr nice! :tada:
    Ólafur Páll Geirsson
    @olafurpg
    @/all the mdoc repo has moved to scalameta/mdoc and the new gitter room is gitter.im/scalameta/mdoc
    the readme docs have moved to a new website https://scalameta.org/mdoc/
    Ólafur Páll Geirsson
    @olafurpg
    You might also be interested in the blog post on how mdoc evaluates Scala code examples https://scalameta.org/mdoc/blog/2019/12/30/introduction.html
    kerr
    @hepin1989
    Did mdox support other languge?like java'?
    And thanks for mdox
    Mdoc
    Ólafur Páll Geirsson
    @olafurpg
    @hepin1989 I'll answer over at https://gitter.im/scalameta/mdoc ;)
    Noel Welsh
    @noelwelsh
    Nice!