Installing Sphinx

In order to work with Sphinx and generate the HTML/PDF documentation you’ll need the following:

  • Python
  • easy_install (included with Python setuptools)
  • LaTeX installation with full extensions (in order to build PDF documentation)

Windows

GeoServer documentation projects all include a make.bat which provides much of the same functionality as the make command. If you wish to install make anyway, it is available as part of the MSYS package.

  1. Download and install Python. Though there are various distributions and versions, the official version 2.5.4 has been tested and works as expected.

  2. Download and install setuptools for Python 2.5

  3. Put python and setuptools (and make if you installed it) in your Path. To do so, go to Control Panel ‣ System ‣ Advanced ‣ Environment Variables. Look for PATH among the system variables, and add the installation locations to the end of the string. For example, if python is installed in C:\Python and setuptools is installed in C:\Python\scripts, add the following to the end of the string:

    ...;C:\Python;C:\Python\scripts

  4. Open a command line window and run:

    easy_install sphinx

  5. To test for a successful installation, in a command line window, navigate to your GeoServer source checkout, change to the doc\user directory, and run:

    make html

    This should generate HTML pages in the doc\user\build\html directory.

Ubuntu

Note

These instructions may work on other Linux distributions as well, but have not been tested.

  1. Open a terminal and type the following command:

    sudo apt-get install python-dev build-essential python-setuptools

    Depending on your system this may trigger the installation of other packages.

  2. Install Sphinx using easy_install:

    sudo easy_install sphinx

  3. To test for a successful installation, navigate to your GeoServer source checkout, go into the doc/user directory and run:

    make html

    This should generate HTML pages in the doc/user/build/html directory.

  4. If you want to generate PDF files this command should get you the necessary tools:

    sudo apt-get install texlive texlive-latex-extra

Mac OS X

Installing Sphinx on Mac OS X is nearly identical to installing Sphinx on a Linux system.

Easy install

If the XCode extensions are installed on the system easy_install should already be available.

To install Sphinx open a terminal window and execute the command:

sudo easy_install sphinx

Depending on the configuration of the system, problems installing Sphinx with easy_install have been known to occur. If this is the case Sphinx can be installed manually.

Manual install

When installing Sphinx manually the templating library it depends on, Jinja2, must also be installed manually. To install Jinja:

  1. Go to http://pypi.python.org/pypi/Jinja2

  2. Download the source tarball Jinja2-2.1.1.tar.gz

  3. Unpack the source tarball and install Jinja:

    tar xzvf Jinja2-2.1.1-tar.gz
cd Jinja2-2.1.1.
python setup.py install

After Jinja is installed follow a similar process to install Sphinx:

  1. Go to http://pypi.python.org/pypi/Sphinx

  2. Download the source tarbell Sphinx-0.6.2.tar.gz

  3. Unpack the source tarball and install Sphinx:

    tar xzvf Sphinx-0.6.2.tar.gz
cd Sphinx-0.6.2
python setup.py install
Previous: Contributing
Next: Workflow