README.md

Terra Docs

Documentation for Terra.

Based on Sponge's documentation tooling.

Local Usage

Set up

1. Clone this project locally.
2. Ensure installed:
   • Python 3.4+ for Sphinx and its dependencies.
   • Node.js & npm for gulp and its dependencies.
   • Graphviz for rendering diagrams.
3. Open project directory in a terminal
4. Set up python virtual environment (optional, recommended - if you want to install dependencies local rather than system-wide):
   • Run python -m venv .venv to create the virtual environment.
   • Activate the virtual environment, this depends on your system setup:
     • Bash - run source .venv/bin/activate
     • Other setups see python documentation.
   • To leave the virtual environment in your shell, simply run deactivate
5. Install python packages
   • If you already have pip installed or are using a virtual environment run pip install -r requirements.txt
   • Otherwise run python -m pip install -r requirements.txt
     • Windows users: If you see a WARNING about adding the \Scripts folder to PATH, do it, then restart terminal. gulp
6. Install Node.js packages to project directory.
   • Run npm install

Running

1. Open project directory in a terminal.
2. If you are using a virtual environment, make sure to activate it first (see step 4).
3. Run npm exec gulp

Gulp will open a browser window displaying the HTML generated by Sphinx for the reStructuredText documentation. Changes made to documentation sources will automatically update the browser view.