We here aims at running a local jekyll instance to serve the documentation for the ROMI project as done by github pages: https://romi.github.io/.

WARNING: You have to choose between a system-wide install (A) OR a conda install (B)!

A - Installing system-wide

NOTE: The official instructions install Ruby & Jekyll system-wide!

Jekyll on macOS

Official source.

Jekyll on Ubuntu

Official Source

B - Installing in a conda environment

Before we install Ruby & Jekyll, we need to make sure we have all the required dependencies.

sudo apt-get install build-essential zlib1g-dev

WARNING: to use Ruby & Jekyll inside a conda environment, do not follow the official source telling you to add environment variables GEM_HOME & PATH to your ~/.bashrc !

  1. Create a conda environment: 
    conda env create -f conda_recipes/environments/romi-github.io.yaml

    or

    conda install -n romi-github.io ruby rb-github-pages -c conda-forge
  2. Make sure the ruby & gem executables are from the conda environment (not system), here named romi-github.io: 
    $ conda activate romi-github.io
$ which ruby
/home/$USER/miniconda3/envs/romi-github.io/bin/ruby
$ which gem
/home/$USER/miniconda3/envs/romi-github.io/bin/gem
  3. Install jekyll, using gem, then update all ruby plugins: 
    gem install jekyll jekyll-feed jekyll-image-size
gem update
  4. Install the dependencies specified in your Gemfile with bundle: 
    bundle install -j4

Troubleshooting:

If you obtain an error at step 3 (gem install [...]) like:

[...]
make: x86_64-conda_cos6-linux-gnu-c++: Command not found
[...]

You are missing gxx_linux-64, install it as follows:

conda install gxx_linux-64

Using a local Jekyll server

We no have to activate the previously created environment romi-github.io and serve the contents of the romi-github.io directory.

  1. Start a local server: 
    conda activate romi-github.io
cd romi.github.io/
export PORT=4000
export HOST=0.0.0.0
bundle exec jekyll serve
  2. You may now open a browser here: http://0.0.0.0:4000/