robotframework.github.com

This repository hosts Robot Framework's public website available at robotframework.github.com. It uses Ruby based tools Jekyll (a static website generator) and jekyll-rst (a reStructuredText plugin), among others.

Important to note: As this site is hosted in GitHub Pages, the master branch hosts the files. The source branch is where the development happens and from where site is deployed to the master branch. You should not therefore change any files in the master branch directly. Rather, do your work in the source branch and deploy to the master.

Table of Contents

Setting up the development environment
Working with the site
Build and deploy

Setting up the development environment

The preferable way to install Ruby is via RVM. Follow install instructions on the linked page to get RVM, then make sure you have Ruby 1.9.3 and Rubygems installed correctly:

$ rvm list

rvm rubies

=* ruby-1.9.3-p362 [ x86_64 ]

# => - current
# =* - current & default
#  * - default

The above means RVM installed correct Ruby version 1.9.3

$ ruby -v 
ruby 1.9.3 p362
$ gem -v
1.8.24

The above means the correct Ruby- and Rubygems-commands work.

If you need to install Ruby 1.9.3 separately, do:

$ rvm install ruby 1.9.3

Next, you need to install Bundler and check it works:

$ gem install bundler
$ bundle --version

On Linux, you might get the following exception:

$ gem install bundler
ERROR: Loading command: install (LoadError)
    cannot load such file -- zlib
ERROR: While executing gem ... (NameError)
    uninitialized constant Gem::Commands::InstallCommand

This means you are missing zlib or zlib-Ruby -bindings. Install them from aptitude and reinstall Ruby with RVM. (The following works on Linux Mint -- see Stackoverflow thread for more details)

$ sudo aptitude install zlib1g-dev
$ rvm reinstall 1.9.3
$ gem install bundler

Next, clone the repository, switch to source branch, and install Ruby dependencies with bundler:

$ git clone https://github.com/robotframework/robotframework.github.com.git
$ cd robotframework.github.com
$ git checkout -b source origin/source 
$ bundle install

Next, install Docutils:

$ sudo pip install docutils

After Docutils, install Pygments:

$ sudo pip install pygments

Robot Framework lexer is part of the official release of Pygments since version 1.6. If pip gives you an earlier version, you need to install the lexer yourself:

$ sudo pip install robotframeworklexer

You should now be able to start working with the site. Run the following command and then open browser and go to http://localhost:4000 to see the site. You can quit the server with Ctrl-c

$ jekyll --server

Working with the site

!IMPORTANT! The site that is available in the web is in the master branch. Do not modify the master branch! Rather, do your changes in source branch and deploy with rake (see below).

The site uses Jekyll to build the site. Jekyll should be installed with bundler as part of Ruby dependencies (described in the last section).

To run the site with local development server, run:

$ jekyll --server

This will run in port 4000 by default. If you want different port, give it as command line arguments. For example:

$ jekyll --server 3000

Now the site is available in port 3000.

The preferable way to run the site during development is however:

$ jekyll --server --auto

This will automatically update the files when you save them after editing, so you just need to hit refresh in your browser to see updated site.

Do commit early and often. To push your changes to remote source branch, use:

$ git push origin source

Building and deploying

Important to note: quit all jekylls that are running as server before deploying!

The website uses Rake to build and deploy the website. This should have been installed as part of Ruby dependencies (see Installation). To see available rake tasks, run:

/path/to/robotframework.github.com $ rake -T

To build the site, run:

/path/to/robotframework.github.com $ rake build

To deploy the site online, you need to first commit all your changes. After committing, run:

/path/to/robotframework.github.com $ rake deploy

The deployment process does the following things:

Builds the project using the build rake task
Checks that you have committed everything. If you have not, git commit -am is run
Copies the builded files to your OS's temp folder
Switches to master branch, copies files over from temp folder
Commits the changes and pushes to remote master.
Switches back to source branch
Notice that you still need to push the source branch yourself to remote with: $ git push origin source