Isaac Van Doren (May 25 2024 at 21:56): Isaac Van Doren (May 25 2024 at 21:56):I just listened to the latest SW Unscripted episode where the guest mentioned how nice it is to be able to view documentation of a definition and then jump directly to the source code. I think it would be great if this was built in to roc docs. Eventually there would probably need to be flexibility to support multiple source code platforms (github, gitlab, self hosted, etc), but as a start, it would be awesome to just be able to link to the source on GitHub. There could either be a flag to enable this, or it could automatically be done if roc docs is run in a git repo that has a github.com remote set.
Thoughts?
Isaac Van Doren (May 25 2024 at 21:57):Or maybe it would be simpler just to include the source files in the pages generated by roc docs
Richard Feldman (May 25 2024 at 22:24):yeah seems simpler to include the source files, but then again as a user I'd prefer GitHub links
Richard Feldman (May 25 2024 at 22:26):I don't want to couple the compiler to GH though
Richard Feldman (May 25 2024 at 22:29):we could do something like having a flag you can pass for like --src-base
Richard Feldman (May 25 2024 at 22:30):so like roc docs --src-base=https://github.com/roc-lang/roc/blob/25f230fda81ef57387dc73cc315a15b5e383752b/crates/compiler/builtins/roc/
Richard Feldman (May 25 2024 at 22:31):and then it would automatically append (for example) Str.roc#L503 to create the link to Str.split, which is located at https://github.com/roc-lang/roc/blob/25f230fda81ef57387dc73cc315a15b5e383752b/crates/compiler/builtins/roc/Str.roc#L503
Richard Feldman (May 25 2024 at 22:36):and actually we could make the fragment come from a CLI arg too, so like roc docs --src-prefix=https://github.com/roc-lang/roc/blob/25f230fda81ef57387dc73cc315a15b5e383752b/crates/compiler/builtins/roc/ --src-suffix=#L@line
Richard Feldman (May 25 2024 at 22:36):and then we'd replace @line with the line number anywhere it appears
Richard Feldman (May 25 2024 at 22:40):@line because it's reserved in URLs and must be percent-encoded, and doesn't have special meaning in terminals, unlike $ and % (which has special meaning in Windows terminals)
Richard Feldman (May 25 2024 at 22:41):actually, I guess the most flexible would be:
roc docs --src-url=https://github.com/roc-lang/roc/blob/25f230fda81ef57387dc73cc315a15b5e383752b/crates/compiler/builtins/roc/@file#L@line
Richard Feldman (May 25 2024 at 22:42):and then we'd replace @file with the file path and @line with the line number
Richard Feldman (May 25 2024 at 22:42):I don't know what URL formats other source code hosting tools use, but I'd hope that would be flexible enough for them? :big_smile:
Isaac Van Doren (May 26 2024 at 03:24):I like that approach a lot!
Isaac Van Doren (May 26 2024 at 03:25):It will work for GitLab also https://gitlab.haskell.org/ghc/ghc/-/blob/98597ad5fca81544d74f721fb508295fd2650232/ghc/Main.hs#L44
Last updated: Jun 16 2026 at 16:19 UTC