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.
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
!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
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