VIC documentation README

This directory contains that builds the VIC website (http://vic.readthedocs.org). Below is a bit of information on how to edit, test, and serve the documentation.

Style

The VIC documentation source files are written in Markdown, and configured with a single YAML configuration file (mkdocs.yml). Mardown also supports some html so that is an option if pure markdown can't get the job done.

Requirements

To edit the documentation, all you need is a text editor.

To build the documentation, there are two requirements:

• Python version 2.6, 2.7, 3.3 or 3.4.
• mkdocs project to build its documentation.

Building and serving the documentation locally

After editing the VIC documentation, and before committing it to the git repository, you'll want to build and serve the docs on your local machine.

build

from the top level of the VIC repository, run:

mkdocs build

serve

from the top level of the VIC repository, run:

mkdocs serve

For more information on how to interact with the built docs, check out the mkdocs documentation.

Read The Docs

The VIC documentation is served by Read the Docs at http://vic.readthedocs.org. This allows us to provide multiple versions of the VIC documentation, served simultaneously from the same location.

Currently, there are three builds (versions) scheduled for the VIC documentation:

1. master - this represents the docs on VIC's master branch
2. develop - this represents the docs on VIC's develop branch
3. VIC.${tag} - this represents the docs for individual tags in VIC's history.