Heron's documentation was primarily built using the following components:
Running the Heron documentation locally requires that you have the following installed:
To get set up on macOS:
$ cd website $ make setup $ make build-static-assets
This will install Gulp and all of the necessary Gulp plugins and build the static assets for the site, as well as some necessary Python libraries.
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:
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).
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/incubator-heron/
You can edit
.md files and they will be automatically updated in your browser.
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.
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.
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
$ 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
website/public and run
git status or
git remote -v, it appears as another heron repo based off of the
$ 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:
website/publicdirectory, commit everything to the
gh-pagesbranch and push to the
upstreamrepo. You can also push to the
gh-pagesbranch of your own fork and verify the site at