How do I link to third party Racket docs in Scribble?

Question

I'm attempting to link to Scribble docs provided by a third party (as opposed to core) library (specifically, data/collection), but I'm having trouble getting it to work.

With these imports:

@require[scribble/manual
         scribble-abbrevs/manual
         scribble/example
         racket/sandbox
         @for-label[(only-in racket
                             (foldl f:foldl)
                             (foldr f:foldr))
                    (only-in data/collection
                             (foldl d:foldl)]]

The following link to Racket built-in docs works:

@racketlink[f:foldl "foldl"]

But this one, to the data/collection version:

@racketlink[d:foldl "foldl"]

... results in the following error:

raco setup: WARNING: undefined tag in <pkgs>/relation/scribblings/relation.scrbl:
raco setup:  (undef "--UNDEFINED:d:foldl--")
raco setup:  ((lib "data/collection.rkt") foldl)

I also attempted using the @tech tag, something like:

@tech[#:doc '(lib "scribblings/data/collection/collections.scrbl")]{"foldl"}

I tried several variants of this and wasn't able to get it to work -- one thing I couldn't uncover in my scanning of the documentation, for instance here, was how the lib link works -- what exactly is the path referring to? Evidently, "scribblings" does not refer to the local scribblings folder but some kind of global documentation path. But how does one know what path to use for a particular library's documentation? This is perhaps more of a secondary question to the primary one being asked above, but any light you can shed here would be helpful.

Answer 1

The problem is that you only install collections-lib. This does not include its documentation which lives at collections-doc.

So either install the package collections-doc or the (meta-)package collections which will include both collections-lib and collections-doc. Then, run raco setup relation to re-render your documentation. This would suffice for your own builds.

You probably should also modify info.rkt so that other people who install your package download the desired dependencies. There are a couple of ways to set this up.

• An easy way is to put collections in deps, which will require users to install the meta-package collections, hence installing both collections-lib and collections-doc.
• A more difficult way is put collections-lib in deps (you did this already) and put collections-doc in build-deps. An advantage of this approach is that users won't be required to download all tools necessary for building documentation if they install your package as a binary package (which will pre-renders the documentation already).