Luke Boswell (Jun 11 2023 at 22:49): Luke Boswell (Jun 11 2023 at 22:49):While updating the docs for basic-cli I noticed the generated links to builtins were not working, so I changed these to manually link to roc-lang.org.
-## Returns `Bool.true` if the first path ends with the second.
+ ## Returns [Bool.true](https://www.roc-lang.org/builtins/Bool#true) if the first path ends with the second.
@Richard Feldman said
Does this work without the parens? e.g. just [Bool.true] on its own, and then the automatic documentation link generator takes care of the rest? (If not, we should probably make it work!)
How do we make these links work?
Should we "inject" the builtins somehow and include generated docs for these alongside the platform/package docs in generated-docs/ folder? Or should we have these automatically link to the roc-lang.org/builtins/...? Or is there another way?
Luke Boswell (Jun 11 2023 at 22:52):If I recall the builtin modules are included in roc cli with rust's include_str macro in /crates/compiler/builtins/src/roc.rs, maybe we could use these somehow?
const RESULT: &str = include_str!("../roc/Result.roc");
const NUM: &str = include_str!("../roc/Num.roc");
const STR: &str = include_str!("../roc/Str.roc");
etc..
One workaround to this issue is if we expose all the builtins in the basic-cli package root, then all of the docs for builtins are included and the generated links work correctly. Would we want the builtins displayed alongside Package modules in docs? I think this is useful as it shows everything that is available. Maybe we could use something visual in the generated HTML to distinguish between these in the documentation to show they are builtins?
Luke Boswell (Jun 12 2023 at 00:58):e.g.
platform "cli"
requires {} { main : Task {} [] }
exposes [
# Package exports
Path,Arg,Dir,Env,File,FileMetadata,Http,Process,Stderr,Stdin,Stdout,Task,Tcp,Url,Utc,
# Built-in exports
Str, Num, Bool, Result, List, Dict, Set, Decode, Encode, Hash, Set, Box,
]
packages {}
imports [Task.{ Task }]
provides [mainForHost]
Or should we have these automatically link to the
roc-lang.org/builtins/...?
is the issue that the auto-links work when we're generating the builtins, because they "know about themselves" as they're being built, but basic-cli doesn't "know about" builtins for auto-linking purposes becasue they aren't included in its build?
Richard Feldman (Jun 12 2023 at 02:21):or is it that auto-linking stopped working at some point? :sweat_smile:
Luke Boswell (Jun 12 2023 at 03:44):I think auto linking works, it's just the docs for builtins dont get included as they aren't included as exposed modules in the root main.roc for the platform. Maybe there is a way to add these manually in the load module step, so they are inclided in the list of exposed modules, but I haven't figured out how to do that yet.
Richard Feldman (Jun 12 2023 at 18:09):I think ideally we'd add to the auto linking logic to automatically include builtins
Richard Feldman (Jun 12 2023 at 18:10):it's a bit tricky though, because I don't think we want to just include all the builtins' .roc files in the same build as the basic-cli docs, as then we'd get all the modules for both builtins and basic-cli jammed together in the output...but then at the same time, we also probably don't want to hardcode the builtins to always resolve to https://roc-lang.org/... because then it would be hard to do doc gen for the builtins themselves locally (e.g. for testing out changes to them)
Richard Feldman (Jun 12 2023 at 18:12):so I think ideally we'd somehow say "if this is genuinely in scope, and it's from a module whose docs I'm not generating, assume that module exists on the same domain where I'm deployed, and link to that"
Richard Feldman (Jun 12 2023 at 18:13):although for that to work I think we still need to hardcode one aspect of the builtins, which is the builtins/ path - and for that I think we can use symbol.is_builtin() probably
Last updated: Jun 16 2026 at 16:19 UTC