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 <mfl...@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 >
____________________ Racket Users list: http://lists.racket-lang.org/users
