Building Documentation

There are two parts of the project that are covered by this documents: Source Code API [1] and the User Manual [2].

Even though those parts are independently hosted and maintained, they are both built on the same framework.

[1]code, compiled
[2]code, compiled

Language and Format

The documentation is written in reSt (reStructuredText). This is a markup language that is compiled to generate html (or pdf).

Requirements

Before working in the documentation you need to install all the requirements and the main repository from the installation guide.

Quick Setup

Type the following commands in your terminal. If you are developing in Windows we recommend you to use Power Shell or similar.

$ cd $INSTALL_DIR
$ git clone https://github.com/BlenderVR/manual.git
$ source venv/bin/activate
$ pip requirements -r source/docs/requirements.txt
$ pip requirements -r manual/requirements.txt
$ deactivate

How to Build

Note

While this generates a local copy of the latest documentation, the BlenderVR project is hooked up with the ReadTheDocs system. This auto-compiles the documentation and make it available online everytime something is committed in the system.

User Manual

$ cd $INSTALL_DIR
$ source venv/bin/activate
$ cd manual
$ make
$ deactivate

This will output the documentation to $INSTALL_DIR/manual/html.

Souce Code API

$ cd $INSTALL_DIR
$ source venv/bin/activate
$ cd source/docs/
$ make
$ deactivate

This will output the documentation to $INSTALL_DIR/source/docs/html.

How to Edit

The .rst files are simple plain text files that can be edited with any text editing tool. Once the file is ready it can be previewed with make, and eventually pushed back to the repository.

There are tools to preview the .rst file during the editing, but they are platform specific. In the Linux and OSX environment one can use InstantRST with vim. Sublime (for OSX) seems to have some tools as well.