[racket] package server + making docs available early

From: Matthew Butterick (mb at mbtype.com)
Date: Tue Feb 11 13:07:18 EST 2014

I'm starting to use the new package-management system in earnest. The whole thing is very well considered, so thank you to Jay & others for the good work.

As I browse existing packages, I keep saying "gee, I'd like to read the docs on foo before I do raco pkg install foo." 

Is there a way to do that?

I'm guessing no, because Scribble encourages authors to document code by relying on evaluations of the code itself. So the docs can't be rendered until the underyling libraries are installed.

OTOH, once the docs are rendered, the dependency ends. So if an author rendered the docs and included a copy with the package source — not just the Scribble sources — those docs could be available independently. (And when someone actually did "raco pkg install foo", the docs would be re-rendered locally, added to the local index, etc.)

In the package database, maybe it would suffice for the author to be able to provide a 'rendered docs' link in addition to a 'source' link. As for hosting the rendered docs, seems like there could be a clever way to do this using github pages — if files are pushed into a branch in the repo named gh-pages, they become publicly accessible at http://authorname.github.io/package. 

Posted on the users mailing list.