Wiki

Clone wiki

main / Setting_up_the_documentation_environment

Setting up the Documentation Environment

The Qualyzer's web site and documentation is created using Sphinx, a Documentation Generator written in Python.

Documentation pages in HTML or PDF are generated from reStructuredText source files (look here for a comprehensive overview of the syntax).

Contents:

<<toc>>

Installing The Documentation Environment

To use Sphinx, you need to install Python. Then, you can either install Sphinx for the entire system or you can install Sphinx in a virtual environment if you want to install various versions of the same packages.

Installing Python

Python 2.4 and up is required to use Sphinx. These steps are about installing Python on Windows. Python should be installed by default on Linux (otherwise, just use your package manager, e.g., apt-get install python).

  1. On Windows, go to the Python Download Page and download the latest version of Python 32 bit in the 2.x series (e.g., 2.6.5). DO NOT DOWNLOAD Python 3.x or the 64 bit version
  2. Install Python (e.g., in C:\Python26).
  3. Ensure that C:\Python is in your System Path (just type python and then exit() in a command line or echo %PATH%).

Note: Python 3.x is backward incompatible with Python 2.x and many Python packages have not been ported to this new line. Many Python packages are not offered in 64bit version for Windows (but it is still possible to build them from the source).

Installing Sphinx the easy way (for the entire system)

Follow these steps if you want to install Sphinx globally, i.e., for the entire system. This is usually suitable if you do not plan to use Python for other projects. These steps are for Windows. On Linux, just use your package manager (e.g., apt-get install python-sphinx).

  1. Download and install setuptools. setuptools is a tool to easily install python packages. Select the setuptools-0.6c11.win32-py2.6.exe version if you have installed Python 2.6.
  2. Add to the System Path C:\Python26\Scripts
  3. In a command line, type easy_install pip
  4. Type pip install sphinx

Note: C:\Python26\Scripts is the directory where most python extensions for windows are stored.

Without easy_install or pip, you would have had to download all the dependencies of Sphinx, unpack the tar.gz files, then type "python setup.py install" for all the dependencies. easy_install manages everything for you: it downloads the latest version of the package you want to install, compile the sources, and place them in the standard directory for python external packages.

Unfortunately, easy_install does not allow you to remove the files that you installed and it does not store the source files in a temporary directory: if something bad happens during the installation, easy_install will download the source files again. pip does not suffer from these limitations, hence the reason for using it.

Installing Sphinx the hard way (using Virtual Environment)

These steps are preferable if you use Python everyday. These steps will create a "virtual environment" where you can download specific versions of python packages. This is useful when dealing with various versions (e.g., you may have one environment for the bleeding edge version of Sphinx and one environment for the stable one).

These steps are for Linux, but can be reproduced on Windows. It assumes that virtualenv is already installed.

  1. cd ~ (replace this by a more suitable location if you want)
  2. mkdir .virtualenvs (the environments will be located in this directory)
  3. virtualenv --no-site-packages .virtualenvs/docs (create an environment)
  4. source .virtualenvs/docs/bin/activate (activate the virtual environment. On Windows, just call activate.bat)
  5. pip install sphinx (install sphinx in the activated environment)
  6. deactivate (to deactivate the environment)

Note: When building the documentation (next sections), always activate the docs environment first.

Building the web site

These steps assume that you already have retrieved the source of the web site and that you are in the site_source directory.

  1. On Linux, type: make html
  2. On Windows, type: make.bat html
  3. A _build/html directory should have been created with the all the web site content (HTML files, css, javascript, etc.).
  4. Open _build/html/index.html to see the website front page.

Building the PDF documentation

These steps assume that you already have retrieved the source of the web site and that you are in the site_source directory.

On Linux, we assume that you have installed a Latex distribution such as texlive. On Windows, you can install MikTeX. Make sure that Latex binaries are on your path (e.g., you can type pdflatex in a command line).

  1. On Linux, type: make latex
  2. On Windows, type: make.bat latex
  3. cd _build/latex
  4. On Linux, type: make all-pdf
  5. On Windows, type: pdflatex Qualyzer.tex
  6. Qualyzer.pdf should have been created.

Documentation Style Guidelines

TBD

Modifying the HTML Site Design

TBD

Updated