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 git@github.com:username/mypackage.git
$ 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/create-gh-pages.sh which contains the following:

#!/usr/bin/env sh

scribble +m --dest-name index.html --dest gh-pages/ --redirect-main  http://download.racket-lang.org/docs/5.3.6/html/ 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 create-gh-pages.sh

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/
$ ./create-gh-pages.sh
$ 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: http://username.github.io/mypackage/

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

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

Using C-Kermit to Exchange Files With Telnet BBS's

Most BBSs that are still running now do so via telnet. In many ways this is great as it allows people from all around the world to access a BBS as if it were local to them. The problem comes though, ...   Read More

Connecting to a Remote Serial Port over TCP/IP

Most modern machines don't have a serial port as standard; you could use a USB to serial lead, however, if you have another machine available that does have a serial port you can access it remotely ove...   Read More

Sign up to get new articles straight to your inbox.

Delivered by FeedBurner

Comments

blog comments powered by Disqus