Judgels documentation guide

This section is intended for developers that want to contribute in writing Judgels documentation.

Introduction

All Judgels documentation is stored in judgels repository, in the directory docs. The documentation is published on Read the Docs, here: http://judgels.readthedocs.org. The documentation will be updated every time there is a commit pushed to judgels repository.

The documentation is written using Sphinx. To use Sphinx, we need Python. To simplify Sphinx installation, we will use virtualenv.

Setup

1. Install Python.

   On Ubuntu:

   sudo apt-get install python
   

   On OS X (via Homebrew):

   brew install python
   

2. Install pip.

   On Ubuntu:

   sudo apt-get install python-pip
   

   On OS X: automatically installed along with Python.

3. Install virtualenv via pip:

   pip install virtualenv
   

4. Go to main documentation directory.

   cd $JUDGELS_BASE_DIR/judgels/docs
   

5. Create virtual environment.

   virtualenv env
   

6. Activate the virtual environment.

   source env/bin/activate
   

Sphinx will be ready in the directory.

Writing documentation

First, try to build the documentation. Run

make html

Sphinx will be installed the first time you run the command.

If everything goes well, a file $JUDGELS_BASE_DIR/judgels/docs/_build/html/index.html will be built. Open it on your browser to see the documentation.

The documentation is written in reStructuredText (RST) syntax. The root documentation source file is docs/index.rst. Please consult reStructuredText Primer for more details on the syntax.