Anton (Aug 06 2024 at 17:52): Anton (Aug 06 2024 at 17:52):I've mentioned this in another topic but we have not discussed it yet:
I think the roc CLI should be able to accept markdown files so it can do roc check for every '''roc code block.
We need all this functionality anyway to check roc code blocks inside doc comments, so exposing this extra convenience for .md files seems logical.
Anton (Aug 06 2024 at 17:53):I mainly want this feature to check all code blocks in the tutorial.md
Anton (Aug 06 2024 at 17:55):It's also nice for packages or platforms that have roc examples in their README.md
Richard Feldman (Aug 06 2024 at 18:17):a challenge with that: what do we consider valid markdown? :sweat_smile:
Richard Feldman (Aug 06 2024 at 18:18):I guess we could just ignore everything except specifically '''roc blocks, and just check those?
Richard Feldman (Aug 06 2024 at 18:18):so then it's not really markdown, but rather "text files with code blocks"
batyoullfly (Aug 06 2024 at 21:11):Could there be some way to provide a context for the code blocks? Like if there’s a specific package/platform/module needed for each example how could you avoid having to paste that import for every block?
Anton (Aug 07 2024 at 09:04):how could you avoid having to paste that import for every block?
I would like to try pasting it for every block, but like this:
### begin header
app [main] { pf: platform "https://github.com/roc-lang/basic-cli/releases/download/0.12.0/Lb8EgiejTUzbggO2HVVuPJFkwvvsfW6LojkLR20kTVE.tar.br" }
import pf.Stdout
import pf.Task
### end header
main =
Stdout.line! "Hello, World!"
This makes it possible to hide it by default but view it using a HTML button or do copy with imports.
I've always found it annoying when copying a docs example in other languages that I then have to go looking for all the right imports.
Anton (Aug 07 2024 at 09:04):We could also use a similar ### begin tests block.
Luke Boswell (Aug 07 2024 at 09:46):Another consideration, is that we may also want to support running roc test as well as roc check. I think that will be useful for modules specifically, as opposed to apps.
I like showing the behaviour of a function using tests sometimes, and I think it would be good to be able to run theses tests in the doc comments.
Kevin Gillette (Aug 10 2024 at 13:54):Having some convention for specifying expression evaluation results (in a specially formatted Roc comment) would be useful, so that not only can code be specified, but also results, which some Roc command could validate as well.
This would be useful for tutorial markdown files, as well as modules which are more about computing some result, such as a time handling package
Anton (Aug 10 2024 at 14:41):I've created #6981 for roc test and #6980 for roc check.
Anton (Aug 10 2024 at 14:52):For "expression evaluation results" I propose ```roc-repl blocks, so for example:
replResult = 1 + 2 * (3 - 4)
expect replResult == "-1 : Num *"
The static-site-gen platform we use for the tutorial would get rid of replResult = and expect replResult = ". So when rendering this becomes:
render_repl.png
Kevin Gillette (Aug 10 2024 at 17:23):Would that be == on the expect line?
Anton (Aug 10 2024 at 17:24):Yes, thanks, I edited the proposal
Kevin Gillette (Aug 10 2024 at 17:25):And would other checks beyond simple equality be permitted? Would multiple expects be permitted per result, i.e. to do property testing ("this is the result of float math, so I'll just say it's between these values")
Kevin Gillette (Aug 10 2024 at 17:31):If so, I'd propose the initial replResult assignment be what causes the rendering of both the expression and the result. Validation would be optional
Kevin Gillette (Aug 10 2024 at 17:31):In terms of code sharing, we could have named headers that could be referred back to explicitly.
### begin header xyz
...
(end of header optional, in which case the whole block is the header)
and then:
### use header xyz
We could also infer stdlib imports for brevity: if you just use qualified symbols, like Num.sqrt, then the tooling could infer the right thing. If you needed an import that looks like something in the stdlib, but is actually external, then you'd need to be explicit
Anton (Aug 10 2024 at 17:39):Things in the stdlib like Num are always automatically imported (in an invisible way)
Anton (Aug 10 2024 at 17:41):In terms of code sharing, we could have named headers that could be referred back to explicitly.
Yeah, that's possible, I would like to start simple and see how that goes
Last updated: Jun 16 2026 at 16:19 UTC