.. _install_sphinx:
Installing Sphinx
=================
In order to work with Sphinx and generate the HTML/PDF documentation you will need the following:
* `Python 3 `_
* `pip3 `_ (Package Installer for Python, included with Python)
To optionally make PDF documentation you will need the following:
* `LaTeX `_ installation with full extensions (in order to build PDF documentation). For more details, see :ref:`install_latex`.
Windows
-------
#. Download and install Python 3. Though there are various distributions and versions, the `official versions `_ have been tested and work as expected.
Put :command:`python` in your Path. To do so, go to :menuselection:`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 :command:`python` is installed in :file:`C:\\Python` add the following to the end of the string:
.. code-block:: bat
...;C:\Python
Confirm availability of Python 3:
.. code-block:: bash
python --version
#. Open a command line window and run:
.. code-block:: bat
cd doc\en
pip3 install -r requirements.txt
#. Confirm availability with:
.. code-block:: bat
sphinx-build --version
sphinx-autobuild --version
#. To test for a successful installation, in a command line window, navigate to your GeoServer source checkout and run:
.. code-block:: bat
mvn clean -f doc/en install
This is the same as running:
.. code-block:: bat
cd doc\en
ant user
ant docguide
ant developer
This should generate HTML pages in the :file:`doc\\en\\target\\user\\html` directory.
Ubuntu
------
.. note:: These instructions may work on other Linux distributions as well, but have not been tested.
#. Open a terminal and type the following command:
.. code-block:: bash
sudo apt-get install python-dev build-essential pip
Depending on your system this may trigger the installation of other packages.
Confirm availability of Python 3:
.. code-block:: bash
python --version
#. Install Sphinx using :command:`pip`:
.. code-block:: bash
cd doc/en
pip3 install -r requirements.txt
#. Confirm availability with:
.. code-block:: bash
sphinx-build --version
sphinx-autobuild --version
#. To test for a successful installation, navigate to your GeoServer source checkout and run:
.. code-block:: bash
mvn clean -f doc/en install
This should generate HTML pages in the :file:`doc/en/target/user/html` directory.
Mac OS X
--------
Installing Sphinx on macOS is nearly identical to installing Sphinx on a Linux system.
#. Example using `homebrew `__ package manager:
.. code-block:: bash
brew install python
Confirm availability of Python 3:
.. code-block:: bash
python --version
#. Use ``pip`` or ``pip3`` to install :command:`sphinx` and related tools:
.. code-block:: bash
cd doc/en
pip3 install -r requirements.txt
#. Confirm availability with:
.. code-block:: bash
sphinx-build --version
sphinx-autobuild --version
#. To test for a successful installation, navigate to your GeoServer source checkout and run:
.. code-block:: bash
mvn clean -f doc/en install