.. _building_documentation:

Building Documentation (Linux OS only)
**************************************

To build the documentation for :mod:`waeup.kofa`, please follow these steps:

Prerequisites
=============

We assume you already installed `waeup.kofa` as explained in
:ref:`installing_linux`. You ran ``bin/buildout`` and can find a script
``bin/waeupdocs``.

Building HTML docs
==================

After successful install go to the root dir, where `waeup.kofa` is
located.

There run::

   $ ./bin/waeupdocs

This will (re-)generate any needed docs.

The output can be found in ``docs/build/html``.

Actually, ``waeupdocs`` is only a wrapper script around the real main
script ``sphinx-build``, which should also be located in your ``bin/``
directory.

You therefore can also run ``bin/sphinx-build`` manually, which will
give you more options, especially, if you want the output to be
created in a different location or similar.

Run::

   $ ./bin/sphinx-build --help

to get a list of options available.

Alternatively, you can also go to ``docs/build`` and run::

   $ make html

Other available formats are listed, when you run only::

   $ make

These other formats will include ``latex``, ``doctest``, ``linkcheck``
and more with a short explanation for each format.


Building PDF docs
=================

We're currently not prepared for PDF, but support is already planned.

Please be aware, that any PDF support will require a full TeX
installation on your system to work.