2. QuickStart

2.1. Installation

Before starting, you first need to install Sphinx, which is done very easily using easy_install or pip command in a command shell:

pip install sphinx --upgrade

Note

Most Linux distributions provide sphinx in their repository therefore if easy_install (or pip) does not work, you may try yum (Fedora) or apt-get (ubuntu).

2.2. Create your own sphinx project

Once sphinx is installed, you can start a new sphinx project. In a shell, type:

sphinx-quickstart

and follow the instructions. Most of the time you simply need to press enter.

However, you will have to enter the project name, your name, the version (put 1 if you don’t know) and select the extension that you will need later on (.txt or .rst to your conveninence but I would recommend rst). If you do not know, select yes to all (note that jsmath raised an error on my distributution).

Note

this is a basic setup. All options will be stored in a file called conf.py, which can be edited at any time later on.

In principle you should now have a file called conf.py, a file called index.rst (or contents.rst) and some directories.

The conf.py file can be edited if you know what you are doing so as to add new extensions, additional html pages, change the authors or version and much more. Here below is the beginning of the conf.py file used to create this documentation:

"""Based on Sphinx configuration example with the proper extensions


"""
# -*- coding: utf-8 -*-
#
# documentation build configuration file, created by
# sphinx-quickstart on Wed Aug 10 16:58:13 2011.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os, sys

###########################ADDON############################
try:
    import easydev
    from easydev import get_path_sphinx_themes
except Exception, e:
    print "Install easydev or set your PYTHONPATH properly"
    raise Exception


version = "0.9.3"
release = "0.9"
project = u'Sphinx and the RST syntax'

The file index.rst is your entry point. Change it to your need.

Next time you want to create a project, you can just copy the conf.py and makefiles into a new directory.

2.3. Compilation

In order to compile the documentation, under linux type:

make html

or:

make latex

and under windows, type:

make.bat html

This command will analyse the files in the source/ directory and create the HTML files into the directory _build/html/ or build/html depending on your configuration file.

There are many more possible outputs. Type make without argument to get help. For example, to build a PDF version, type:

make latexpdf

Now, it is time to edit your main file index.rst or contents.rst and to learn about the RST and Sphinx syntaxes.