[racket] package server + making docs available early

I let people know today that my Pollen package was available on Github. It
took about 4 seconds for someone to ask "how do I read the docs without
installing the software?"

So until there's a Racket-approved solution, I made the docs available
here: http://mbutterick.github.io/pollen/doc/

If it helps someone else, this involved two steps.

1) Render your docs into your source repo. This command will render a set
of Scribble HTML pages into the directory 'doc', and resolve
cross-references into docs.racket-lang.org.

cd /path/to/repo/
scribble --dest-name doc --htmls +m --redirect-main
http://docs.racket-lang.org/ scribblings/main.scrbl

2) Make a gh-pages branch in your repo and push your changes into it. The
gh-pages branch has to be an orphan branch, which you add like this:

git checkout --orphan gh-pages

Then push it to Github normally. Your docs will be viewable at
http://username.github.com/reponame/doc.

After that, re-render the docs when you like, and keep gh-pages in sync by
whatever method you like. (e.g., git rebase master)





On Tue, Feb 11, 2014 at 10:15 AM, Matthew Flatt <mflatt at cs.utah.edu> wrote:

> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20140501/403ebc88/attachment.html>