Skip to content

Docs

Jump to bottom
Karl W. Schulz edited this page Oct 7, 2020 · 7 revisions

Github Pages

The current docs for the tutorial development work are housed on the gh-pages branch of this repository. When new changes are pushed to this branch, they will automatically get built using Jekyll and pushed to the following URL: https://openhpc.github.io/cloudwg/

Note that the markdown files for the tutorial are currently housed in the repo in the tutorials/pearc20 subdirectory (https://github.com/openhpc/cloudwg/tree/gh-pages/tutorials/pearc20)

A quick refrence on kramdown markdown is available here: https://kramdown.gettalong.org/quickref.html

Developing documentation locally

Prior to pushing changes to the gh-pages branch, you can edit and view changes by running a local Jekyll server. There are a variety of ways to do this, but one way is to use a container-based install of Jekyll. Assuming you have Docker installed locally, you can pull a pre-built container from Karl's dockerhub account for this purpose and fire up locally. Note that you may need sudo for docker commands depending on your local OS. Also, adjust the -v option to correctly match whatever local file system you wish to mount. The assumption here is that you have cloned the repo locally on your system and will access the repo inside the container via the file system mount from the host. This also assumes that your local clone currently has the gh-pages branch checked out.

  1. pull down container and execute. This will throw you into a bash shell of the container.
$ docker run -p 4000:4000 -it -v /Users/karl:/root koomietx/jekyll:v1.2
  1. launch jekyll server
root@412e82f93c8c $ cd repos/cloudwg     # <-- adjust accordingly for your local path
root@412e82f93c8c $ jekyll serve --force-polling --config _config-devel.yml --host 0.0.0.0

If all goes smoothly above, you should see a message like the following indicating that a local server is running on port 4000:

Configuration file: /root/repos/cloudwg/_config-devel.yml
            Source: /root/repos/cloudwg
       Destination: /root/repos/cloudwg/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 1.962 seconds.
 Auto-regeneration: enabled for '/root/repos/cloudwg'
    Server address: http://0.0.0.0:4000
  Server running... press ctrl-c to stop.

At this point, you can point your browser to http://localhost:4000 and should see the site. You can now make changes to markdown files and they should immediately be visible via a browser reload.

Additional comments:

  • When running locally, you want to access the Jekyll config file housed in _config-devel.yml. However, Github will use the _config.yml file. These two files are identical except for the way the theme is specified. In general, you should not have to mess with these files, but if you do, they should be kept consistent.

  • changes to markdown files should be picked up instantly without having to restart the Jekyll server. However, config or layout changes (e.g. changes to _config-devel.yml will require a server restart).

Clone this wiki locally