How to build documentation
==========================

Currently there are 3 different documents available: simulavr documentation (from
texinfo source), simulavr documentation (from reST text sources by Sphinx) and
api documentation generated by doxygen

Simulavr documentation (texinfo)
--------------------------------

.. note:: texinfo documentation is deprecated!

Prerequisites for this is, that you have installed tex and makeinfo. This will
be detected at configure time. (e.g. when you run './configure'!)

Documentation will be generated from texinfo file. You'll find source at
'doc/simulavr.texi'. From this a info file ('simulavr.info') will be generated
automatically with the default make target::

  > make
  
But you can generate it explicit by::

  > make info
  
If you want to generate a pdf file from texinfo source, you can do this with::

  > make pdf
  
The result can be found in 'doc/simulavr.pdf'.

Simulavr documentation (Sphinx)
-------------------------------

Prerequisites to build this documentation is python, at least in version 2.4,
Sphinx python package and rst2pdf python package.

To check, if you have python and the right version::

  > python -V
  
Sphinx and rst2pdf are python packages. Simplest way to install python packages
is to use 'easy_install' command. To check, if easy_install is available::

  > easy_install -h
  
If you get the help output for this command, everything is ok. If not, you have
to install a python package called setuptools. Go to
http://pypi.python.org/pypi/setuptools and follow instructions there. Sometimes
you can get it too by package management system of your distribution. For example
on Ubuntu you have to install deb package 'python-setuptools'.

Once you have 'easy_install' you can install Sphinx and rst2pdf::

  > easy-install Sphinx rst2pdf
  
If you are not sure, if it is installed, you can try::

  > python -c "import sphinx"
  > python -c "import rst2pdf"
  
If you not get exeptions on both commands, then both packages are installed
sucessfull.

To build then documentation::

  > make sphinx-doc
  
This will generate html and pdf output. You can find it in 'doc/doc_build/html/*'
and 'doc/doc_build/pdf/simulavr.pdf'
  
API documentation
-----------------

Prerequisites for this is, that you have installed doxygen. If you want to get
also dependency and inheritance graphs, then you need also graphviz package. This
will be detected at configure time. (e.g. when you run './configure'!)

To check, if it is installed::

  > doxygen -h
  > dot -h
  
If both commands are found you'll see commandline help for this commands.

Then you can generate api documentation::

  > make doxygen-doc

