Rendering Racket Package Scribblings on Github Using gh-pages

  /     /   Racket     Tutorial    

With the new package management system for Racket, there is a need to host documentation for the package somewhere. Github allows you to host web pages, and hence a package's documentation, by putting them into the gh-pages branch of your repository. This can be a little awkward to do though, so this article will demonstrate an easy way to manage the process.

Reorganising your Directory Structure

If your package was in /home/you/dev/mypackage/, you would want to reorganize it so that the contents of this directory is now in /home/you/dev/mypackage/master/:

$ cd /home/you/dev/mypackage/
$ mkdir master
$ mv * master/

# You may need to move additional hidden files to the
# ones in the line below
$ mv .g* master/

Now you can set up the gh-pages directory, where you will store the scribblings rendered as html:

$ mkdir gh-pages

# Clone your `master` branch into the `gh-pages` directory:
$ cd /home/you/dev/mypackage/gh-pages
$ git clone
$ mv mypackage/* .

# As above, you may need to move additional hidden files to
# the ones in the line below
$ mv mypackage/.g* .

$ rmdir mypackage

# Create a clean orphan branch: gh-pages
$ git checkout --orphan gh-pages
$ git rm -rf .

Render the Package's Scribblings to gh-pages as html

To render the package's scribblings to html and store them in the gh-pages branch you can create a script called /home/you/dev/mypackage/ which contains the following:

#!/usr/bin/env sh

scribble +m --dest-name index.html --dest gh-pages/ --redirect-main master/collection/scribblings/collection.scrbl

Where 5.3.6 is the version of Racket's documentation that you want to cross reference and collection is the name of the collection within the package that you want to render.

You will need to make the script executable with:

$ chmod +x

Now you just need to run it, add the rendered files into the gh-pages branch in the normal way and push them to github:

$ cd /home/you/dev/mypackage/
$ ./
$ cd /home/you/dev/mypackage/gh-pages
$ git add *.html *.css *.js
$ git commit -am "Import project into repo"
$ git push origin gh-pages

Accessing the Documentation

You will now be able to access the rendered documentation at:

You may want to point to it from your github repository's README, if you have one, as well as set the repository's homepage to the url. Finally you can define homepage within a collection's info.rkt file to point to the url.

Where Now?

This should be enough to get you started and there are may variations on this that you could try. You may also want to automate the process of generating the scribblings with a Makefile, or perhaps using a git hook.

Creative Commons License
Rendering Racket Package Scribblings on Github Using gh-pages by Lawrence Woodman is licensed under a Creative Commons Attribution 4.0 International License.

Related Articles

Transferring Files to and from CP/M .D71 Disk Images Using ctools

Using Vice to emulate a Commodore 128 running CP/M works very well, but it isn't easy to get CP/M files directly onto and off a .D64/.D71 disk image. The easiest way to do this under Linux is to use c...   Read More

Emulating a CP/M System With z80pack

z80pack is great for creating an emulated CP/M system. It can either be used to create a general CP/M system or can emulate a specific system such as an IMSAI or ALTAIR including a graphical front-pan...   Read More

How to Make Thunderbird Feel Like Geary

Geary is a lightweight email client inspired by gmail's interface. Its simple minimalistic interface is quite pleasant to use and initially I was really pleased to switch to it from Thunderbird. Howe...   Read More

Adding a Basic Stub to a VIC-20 Assembly Language Program

To make machine language programs more friendly it is nice to add a basic stub which contains a line with a SYS statement to start the code. This is easy to do on the Vic-20 and the process gives you ...   Read More

Beginning Assembly Programming on the Commodore VIC-20

The Commodore Vic-20 is a great machine to learn an assembly language on. It was released in 1981 and was the first computer to sell one million units, which contributes to its popularity today. The ...   Read More

Sign up to get new articles straight to your inbox.

Delivered by FeedBurner


blog comments powered by Disqus