[racket] package server + making docs available early

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Tue Feb 11 13:15:25 EST 2014

Readily accessible documentation is the biggest missing piece in the
current package server. We have plans, and those plans involve the
server side --- so no new release will be needed, assuming that our
ideas work.

The server should be able to build documentation, because we also
expect some server to run package test suites, all within a sandbox.
But it will take some time, yet, to set up.

At Tue, 11 Feb 2014 10:07:18 -0800, Matthew Butterick wrote:
> 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. 
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users

Posted on the users mailing list.