Heron Documentation

Heron's documentation was primarily built using the following components:

Hugo --- Static site generator
GulpJS --- Build tool for static assets
Twitter Bootstrap --- Sass/CSS and JavaScript

Documentation Setup

Running the Heron documentation locally requires that you have the following installed:

OS X Setup

To install Node.js and npm on Mac OS X, make sure that you have Homebrew installed and run:

$ brew update && brew install nvm && source $(brew --prefix nvm)/nvm.sh
$ nvm install node
$ curl -L https://www.npmjs.com/install.sh | sh

Once this has completed:

$ cd website
$ make setup
$ make build-static-assets

This will install Hugo, Gulp, and all of the necessary Gulp plugins and build the static assets for the site.

Other Operating Systems Setup

Although the documentation is currently set up to be built and run on OS X, it's also possible to do so on other systems. In addition to Node.js and npm you will also need to install Hugo. Once those are installed:

Navigate to the website folder
Run npm install
Run make build-static-assets (this will build all of the necessary static assets, i.e. CSS, Javascript, etc.)

Building the Docs Locally

To build the docs locally:

$ make site

This will generate a full build of the docs in the public folder, a full build of the static assets in the static folder, and check all links. If broken links are found, see linkchecker-errors.csv (you can safely leave this file in your directory, as it is ignored by Git).

Running the Site Locally

To serve the site locally:

$ make serve

This will run the docs locally on localhost:1313. Navigate to localhost:1313/heron to see the served docs. Or open the browser from the command line:

$ open http://localhost:1313/heron

Working on Static Assets

If you‘d like to work on the site’s static assets (Sass/CSS, JavaScript, etc.), you can run make develop-static-assets. This will build all of the static assets in the assets folder, store the build artifacts in the static folder, and then watch the assets folder for changes, rebuilding when changes are made.

Checking Links

To verify that the links in the docs are all valid, make sure wget is installed and run make linkchecker, which will produce a report of broken links. However, no URL of parent webpages that contain broken links will be reported, but one can use grep command to find those parent webpages.

Publishing the Site

The content on the twitter.github.io/heron website is what is committed on the gh-pages branch of the Heron repo. To simplify publishing docs generated from master onto the gh-pages branch, the output directory of the site build process (i.e. website/public) is a submodule that points to the gh-pages branch of the heron repo.

A one-time setup is required to initialize the website/public submodule:

$ rm -rf website/public
$ git submodule update --init
$ cd website/public
$ git checkout gh-pages
$ git remote rename origin upstream

With the submodule in place, you will notice that when you cd into website/public and run git status or git remote -v, it appears as another heron repo based off of the gh-pages branch.

$ git status
On branch master
Your branch is up-to-date with 'upstream/master'.
$ cd website/public
$ git status
On branch gh-pages
Your branch is up-to-date with 'upstream/gh-pages'.

To publish the site docs:

Make the site as described in the above section. Verify all links are valid.
Change to the website/public directory, commit everything to the gh-pages branch and push to the upstream repo. You can also push to the gh-pages branch of your own fork and verify the site at http://[username].github.io/heron.