website/README.md

<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
-->
# Heron Documentation

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

* [Hugo](http://gohugo.io) --- Static site generator
* [GulpJS](http://gulpjs.com) --- Build tool for static assets
* [Twitter Bootstrap](http://getbootstrap.com) --- Sass/CSS and JavaScript

## Documentation Setup

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

* [Make](https://www.gnu.org/software/make/)
* [Node.js](https://nodejs.org/en/)
* [npm](https://www.npmjs.com/)
* [pip](https://pypi.python.org/pypi/pip) - install `PyYAML>=3.12`
* [Go](https://golang.org) (make sure that your `GOPATH` and `GOROOT` are set)

### macOS setup

To get set up on macOS:

```bash
$ 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.

### 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](https://github.com/spf13/hugo/releases). Once those
are installed:

1. Navigate to the `website` folder
2. Run `npm install`
3. Run `make site`

## Building the Docs Locally

To build the docs locally:

```bash
$ 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:

```bash
$ make serve
```

This will run the docs locally on `localhost:1313`. Navigate to
[localhost:1313/heron](http://localhost:1313/heron) to see the served docs. Or
open the browser from the command line:

```bash
$ open http://localhost:1313/incubator-heron/
```

You can edit `.md` files and they will be automatically updated in your browser.

## 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](http://twitter.github.io/heron)
website is what is committed on the [gh-pages
branch](https://github.com/apache/incubator-heron/tree/gh-pages) 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.

```bash
$ 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:

1. Make the site as described in the above section. Verify all links are valid.
2. 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`.