<div dir="ltr">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?"<div><div><br></div><div>
So until there's a Racket-approved solution, I made the docs available here: <a href="http://mbutterick.github.io/pollen/doc/">http://mbutterick.github.io/pollen/doc/</a></div><div><br></div><div>If it helps someone else, this involved two steps.</div>
<div><br></div><div>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 <a href="http://docs.racket-lang.org">docs.racket-lang.org</a>.</div>
<div><div><br></div><div>cd /path/to/repo/</div><div>scribble --dest-name doc --htmls +m --redirect-main <a href="http://docs.racket-lang.org/">http://docs.racket-lang.org/</a> scribblings/main.scrbl<br></div></div><div class="gmail_extra">
<br></div><div class="gmail_extra">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:</div><div class="gmail_extra"><br></div><div class="gmail_extra">
git checkout --orphan gh-pages<br></div><div class="gmail_extra"><br></div><div class="gmail_extra">Then push it to Github normally. Your docs will be viewable at <a href="http://username.github.com/reponame/doc">http://username.github.com/reponame/doc</a>.</div>
<div class="gmail_extra"><br></div><div class="gmail_extra">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)</div><div class="gmail_extra"><br>
</div><div class="gmail_extra"><br></div><div class="gmail_extra"><br></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Feb 11, 2014 at 10:15 AM, Matthew Flatt <span dir="ltr"><<a href="mailto:mflatt@cs.utah.edu" target="_blank">mflatt@cs.utah.edu</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Readily accessible documentation is the biggest missing piece in the<br>

current package server. We have plans, and those plans involve the<br>
server side --- so no new release will be needed, assuming that our<br>
ideas work.<br>
<br>
The server should be able to build documentation, because we also<br>
expect some server to run package test suites, all within a sandbox.<br>
But it will take some time, yet, to set up.<br>
<div><div class="h5"><br>
At Tue, 11 Feb 2014 10:07:18 -0800, Matthew Butterick wrote:<br>
> I'm starting to use the new package-management system in earnest. The whole<br>
> thing is very well considered, so thank you to Jay & others for the good work.<br>
><br>
> As I browse existing packages, I keep saying "gee, I'd like to read the docs<br>
> on foo before I do raco pkg install foo."<br>
><br>
> Is there a way to do that?<br>
><br>
> I'm guessing no, because Scribble encourages authors to document code by<br>
> relying on evaluations of the code itself. So the docs can't be rendered until<br>
> the underyling libraries are installed.<br>
><br>
> OTOH, once the docs are rendered, the dependency ends. So if an author<br>
> rendered the docs and included a copy with the package source — not just the<br>
> Scribble sources — those docs could be available independently. (And when<br>
> someone actually did "raco pkg install foo", the docs would be re-rendered<br>
> locally, added to the local index, etc.)<br>
><br>
> In the package database, maybe it would suffice for the author to be able to<br>
> provide a 'rendered docs' link in addition to a 'source' link. As for hosting<br>
> the rendered docs, seems like there could be a clever way to do this using<br>
> github pages — if files are pushed into a branch in the repo named gh-pages,<br>
> they become publicly accessible at <a href="http://authorname.github.io/package" target="_blank">http://authorname.github.io/package</a>.<br>
</div></div>> ____________________<br>
>   Racket Users list:<br>
>   <a href="http://lists.racket-lang.org/users" target="_blank">http://lists.racket-lang.org/users</a><br>
</blockquote></div><br></div></div></div>