I wish scribble was able to read-syntax a module file, extract the function headers and the contracts so that calling something like @defproc/auto[foo]{some text}) would generate the docs signature automatically
srcdoc is good, but I want to put all the text and examples in a separate file, and is still verbose as it forces to repeat the argument names. It would be nice to use the function header’s ids automatically, with optional renaming.
or a variant of srcdoc that exports the relevant information
That suddenly sounds very doable :smile: I’ll write it down on my todolist, but that’s probably not going to reach the top before 2045
Wouldn’t work in general though, right?
For example, in https://github.com/racket/racket/pull/3743/files#diff-ebebe254faf92cfeb24f73f79e1568a1c7eeae72299e8a7cca28e57b6cccdbd5R577
how would you extract the information from inclusive-range?
Obviously, for such cases you just revert to defproc
Tackling forms is also usually more complicated/ad-hoc, so I would consider only autodoc for functions initially
@thom has joined the channel
It sounds as if it should be fine to use raco setup --only --pkgs <pkg-name> for speed most of the time during development, but use raco setup (and fix corresponding problems) before pushing changes. :slightly_smiling_face:
I was curious how hard this would be so I made a little prototype: https://gist.github.com/Bogdanp/ece1b1ed7204506ad38d94d8ea1d7d5b .
This seems to work, but I’m guessing it probably won’t work during package setup, because it won’t be able to resolve the paths (I think) and it’ll for sure fail for built packages.
Usage looks like:
@autodoc["test.rkt" foo]
@autodoc["test.rkt" foo]{Some description.}
@autodoc[some/mod bar]
That’s awesome :smile:
@popa.bogdanp It should work for built packages if the source file is present, no? At least this works for me: @autodoc[racket/string string-suffix?]
Making progress: @autodoc[racket/string string-join]
> It should work for built packages if the source file is present, no? Yup
(damnit, I’m not supposed to do that today!! :smile: )
Haha
I posted the snippet just as my workday started so it’s out of my hands now!
@ivan.lapcha has joined the channel
@juan.carreon has joined the channel
> damnit, I’m not supposed to do that today!! It’s called Racket addiction. :wink:
Further progress:
Unfortunately there are no explicit contracts in racket/string, only calls to raise-argument-error. But that’s okay since it’s meant for new libraries anyway. Also, ideally, it will be fully customizable, so as to do most of the work, but let the user tweak the remaining bits (and reverting to defproc in the worst case, with little effort)
I’m writing a summary of many of the things I learned from this channel (and will publish that on Github).
One thing just got me confused, though: From what I understood, a package can be re-installed with either $ raco pkg update -n <package-name> ../<working-dir> or $ raco setup <module-name> Are there situations when one is preferred over the other? (In any case, I can see the second version is shorter. :wink:)
> I posted the snippet just as my workday started so it’s out of my hands now! @popa.bogdanp Updates are welcome though. :wink: (as far as necessary)
Yeah, that’s the consensus. Does anyone have a GHA or git push hook or something that will do this for you? I’m a big fan of not having to remember to do things.
The former one is an update and the latter is setup. Update is followed by a setup as part of that process.
Also, update is not really meaningful for packages that are installed in a directory
That’s more useful when the pkg source is elsewhere and you want to pull down the latest.
Not sure this is helping. :)
I would not ever use raco pkg update with a linked package, personally. The only thing you’re accomplishing with that is that it runs raco setup --pkgs <package-name>.
any idea how to cross-compile on CS? I’m running raco exe on an x86 Linux machine and would like to make a FreeBSD/x86 executable.
You’ll need to use a snapshot version of Racket and build that same version for FreeBSD (I’m not aware of any snapshots for FreeBSD) then see
• https://www.cs.utah.edu/plt/snapshots/current/doc/raco/cross-system.html and • https://www.cs.utah.edu/plt/snapshots/current/doc/inside/ios-cross-compilation.html?q=inside (optional)
why is a snapshot version needed? is this some cutting-edge functionality? (In other words, if I wait till 8.1 is out, can I just work with 8.1 rather than snapshots?)
it makes me nervous to roll with snapshots in production :grimacing: