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.

I cannot reproduce the problem. `@racketlink[d:foldl "foldl"]` works as expected for me. Did you install `collections` or `collections-lib`? — Sorawee Porncharoenwase, Mar 12 '20 at 22:23
huh.. "collections-lib" is included in `(deps ...` in my `info.rkt`. Also tried adding it to `(build-deps ...`. Still, same error. Is there anywhere else it needs to be added to be found as a documentation-stage dependency? My library code is able to find the functions in `data/collection`. — mindthief, Mar 12 '20 at 22:37
Ok, I removed and then reinstalled the package using `raco` and that seemed to get rid of the error message. Is it the case that when new deps are added in `info.rkt`, this needs to be done? At the moment, building the docs doesn't complain anymore, but the generated html output still shows a dead link. I think it's because `data/collection` docs aren't locally available on my machine. Do you happen to know how to build those docs locally? If you'd like to post any of these as an answer, am happy to accept. Would also appreciate any clarifications about the `lib` arg above. — mindthief, Mar 13 '20 at 00:12
FTR it looks like the issue didn't go away after all. In case anyone is interested in getting to the bottom of this, the package I'm building is [this one](https://github.com/countvajhula/relation/tree/4d654eae576a395b332af0546f291a723f674a9e), pegged. Running `make` shows the build options. — mindthief, Mar 14 '20 at 16:44

score 1 · Accepted Answer · answered Mar 15 '20 at 11:29

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).

Thank you, that did the trick, and good to know about the consideration re: binary packages. I guess there's some difference between `raco setup ` and `raco setup --pkg ` since when I initially did the latter after adding the correct dependencies, the error message was still present, but running the former worked. Appreciate the help! — mindthief, Mar 16 '20 at 02:55

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

1 Answers1