raco docs only sometimes installed?

[Brian Beckman]

I am having problems installing raco docs, meaning I want

    raco docs foo-pkg

to work no matter how I installed the package. To give you an example of a failure, I created a racket package and put it up on the raco pkg server:

    https://pkgd.racket-lang.org/pkgn/package/bleir-sandbox

which refers to a github repo

    https://github.com/rebcabin/bleir-sandbox

I then created two, fresh, Ubuntu 18.04 virtual machines via Virtual Box. On both machines, I installed racket 8.2 as follows:

    sudo apt install racket

    sudo add-apt-repository ppa:plt/racket

    sudo apt update

    sudo apt upgrade

On machine 1, I did

    raco pkg install bleir-sandbox

    raco test .local/share/racket/8.2/pkgs/bleir-sanbox  # all copacetic

    raco docs bleir-sandbox

WORKS! Scribble docs show up in Firefox

On machine 2, I did

    git clone https://github.com/rebcabin/bleir-sandbox.git

    cd bleir-sandbox

    git checkout master

    cd ..

    raco pkg install bleir-sandbox

    raco test .local/share/racket/8.2/pkgs/bleir-sandbox  # everything copacetic

    raco docs bleir-sandbox

NO MATCHES FOUND! Raco docs show no entries found for bleir-sandbox

Worse yet, if I try on machine 2 to do it the working way, it doesn't work, and it fails forever more.

    raco pkg remove bleir-sandbox

    raco pkg install bleir-sandbox

    raco test .local/share/racket/8.2/pkgs/bleir-sanbox  # all copacetic

    raco docs bleir-sandbox

NO MATCHES FOUND!, NEVER EVER AGAIN

I flushed Firefox cache, I did sudo racket setup for everything, and more trial-and-error.

Incidentally, some packages installed from the cloud also don't install docs. For example,

    raco pkg install beautiful-racket  # the package works great

    raco docs beautiful-racket  # NOT FOUND!

I have similar problems on Ubuntu 21, but racket doesn't install things in .local/share/racket/8.2. In fact, I've been unable to find out where racket is installing packages on Ubuntu 21 (i.e., in what directories), even thoug

    raco pkg show

shows all the packages I expect to see, and they all apparently work properly except for doc install.

Would someone be so kind as to help me

1) understand what the heck is going on?

2) find a reliable, robust way to always install the docs on the packages I develop.

[schle...@gmail.com]

I am not sure what your intent is with 2 exactly.

Is it to install the package you have checked out with git?

If that's the case change the sequence to:

git clone https://github.com/rebcabin/bleir-sandbox.git

cd bleir-sandbox

git checkout master

raco pkg install

raco setup bleir-sandbox

raco test bleir-sandbox

raco docs bleir-sandbox

`raco setup bleir-sandbox` shouldn't be necessary because raco pkg install would already do that after linking the local package source, but you can use that in case you modify the source locally to regenerate the docs.

`raco pkg install` installs/links the folder where you are at as a package (usually for development of packages).

While `raco pkg install bleir-sandbox` installs the package from the package index and `cd ..` followed by `raco pkg install ./bleir-sandbox` would install the local subdirectory as a linked package.

Lastly if creating a local checkout for development is your intent you can shorten it to:

raco pkg install --clone https://github.com/rebcabin/bleir-sandbox.git

raco test bleir-sandbox

raco docs bleir-sandbox

This uses the collection names for test and docs commands because they automatically point towards the installed package.

If you install a local directory with `raco pkg install <path-that-can't-be-mistaken-as-a-package-name>` or `raco pkg install` within a folder, you can also do `raco test ./bleir-sandbox` or `raco test .` respectively.

For the packages where the docs don't work, can you execute `raco setup collection-name` and see/post whether that command outputs any errors?

I have had the case where racket was installed in a way that `raco setup` was unable to write to the directories where it tries to generate its docs occasionally, but that is highly dependent on the linux distribution and how its racket installation is setup. If the default racket install on ubuntu doesn't work for some reason you could always try to install racket locally somewhere in your home directory an test whether it works with that racket version, if it works with the local one, but not the ubuntu one, then I am not sure what is going on.

Because I was assuming the ubuntu package should be setup correctly.

Maybe it is setup in a way where raco setup requires sudo / root, in that case I might try to change the permissions so that root is not required, but I am not on ubuntu, so you should get tips from somebody else for that, probably.

You can do a local install by downloading racket from the website, using the installer and choosing local install.

Hope this wasn't confusing and helped you.

Anyways I think for development of packages --clone is the way to go, see the docs at: https://docs.racket-lang.org/pkg/cmdline.html#%28part._raco-pkg-install%29

Simon

[Brian Beckman]

This is helpful! Thank you. Gives me a few more options to try, though I still don't have a perfect solution.

Regarding intent, yes, I want to have a development environment based on a git clone, with a package behavior that mimics identically the experience seen by someone who downloaded my package from the pkgd.racket-lang.org site. I'm close: the only things that don't jibe are the documentation installations. I'm not blocked: I can test the pkgd distro on a virtual machine that never made the mistake of installing from the git clone, and in the development environment, I can check the scribble docs by finding them in their squirrel hole on the hard drive. It's just that the dream of a development environment that's identical to a user's experience seems out of reach, at least till I try out some of your ideas. Thanks again.