Installing Sphinx

In order to work with Sphinx (>= 1.7.0) and generate the HTML/PDF documentation you’ll need the following:

  • Python

  • pip (Package Installer for Python, included with Python >= 2.7.9 and Python >= 3.4)

  • LaTeX installation with full extensions (in order to build PDF documentation). For more details, see Installing LaTeX.

Windows

  1. Download and install Python. Though there are various distributions and versions, the official versions have been tested and work as expected.

  2. Put python 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 add the following to the end of the string:

    ...;C:\Python
    
  3. Open a command line window and run:

    pip install sphinx
    
  4. To test for a successful installation, in a command line window, navigate to your GeoServer source checkout and run:

    mvn clean -f doc/en install
    

    This should generate HTML pages in the doc\en\target\user\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 pip
    

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

  2. Install Sphinx using pip:

    pip install --user sphinx
    
  3. To test for a successful installation, navigate to your GeoServer source checkout and run:

    mvn clean -f doc/en install
    

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

Mac OS X

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

Confirm availability of python:

python --version

Use pip to install sphinx:

pip install sphinx

Tip

Users of homebrew package manager can install with:

brew install python

Then use pip to install sphinx:

pip3 install sphinx

Home brew installs python into /usr/local and does not require sudo privileges.

Confirm availability with:

sphinx-build --version
sphinx-build 1.8.4

To test for a successful installation, navigate to your GeoServer source checkout and run:

mvn clean -f doc/en install
Previous: Contributing