I have been reading the docs a lot lately as I have been building a couple
internal tools at my work using Racket. It has been awesome.
The docs are some of the best I have used, second only to maybe the Python
standard docs (for reasons largely unrelated to what I'm posting about here).
My only real beef with the Racket docs are the layout of packages; there is no
clear distinction between docs for standard library items and docs for
community provided libs. I like that all the docs are centralized, even for
community provided packages. It's also great that packages are broken up by
category. However, it is frustrating that the difference between stdlib
packages and community packages can't be differentiated at a glance. One has to
first dive into the docs for a particular package to determine where it is
from. It would be nice to have the distinction clearly separated on the main
docs.racket-lang.org page.
Maybe there is something I am missing, but as someone who is relatively new to
the ecosystem, I can say it isn't clear at first blush how to differentiate. In
fact, I am still not totally clear what all is included with a racket install.
The only sure-fire way I know how to check is by traversing the installed
"collects" and "share/pkg" directories.
For instance, one way to separate packages on the docs page might be:
Minimal Racket libs:
* A
* B
* C
Full Racket libs (in addition to minimal Racket):
* D
* E
* F
Community Supported libs:
* G
* H
* I
So, I guess my question is threefold:
1. Is there some way to differentiate that I am missing?
2. If there isn't, does this bother anyone else, or is it just me?
3. If this is an actual issue, how might I go about rectifying it? I am
happy to submit code to change the behavior of the doc generation. Some
pointers as to where to look would be helpful in that case. The only place I
have found that seems to be right is in the pkg-build repo here:
https://github.com/racket/pkg-build/blob/master/extract-doc.rkt
Other than that, I am not yet clear how/when the extracted docs are posted
to the docs page.
--
You received this message because you are subscribed to the Google Groups
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
