ARKODE User Guide
=================

In this directory and below is the ARKODE User Guide. The files are written
using the ReST [1] formatting, which is parsed into final formats using the
Sphinx formatting engine [2].

Here are some benefits of using ReST + Sphinx:

- ReST is very readable in its raw form. It has minimal mark-up
  and is in plain text.
- Since the document sources are included in the ARKODE source code,
  all the documents may therefore be rebuilt and accessed even without
  the internet.
- Sphinx can parse the documents into many convenient formats, most
  notably HTML and a PDF.


Prerequisites:
--------------

To build the docs, you must first have Sphinx [2] installed, as well
as Python [3], and the Sphinx Fortran "domain" extension [4].  To
build the HTML version of the documentation, you'll also need to
install the Bootstrap Sphinx Theme [5].  Information on building these
items is included in the "Usage.txt" file one directory up from this
folder.


Building the documentation:
---------------------------

To build the documents in HTML, use the command:

      $ make html

If that is successful, open the file build/html/index.html in your web
browser (relative to this directory).

To build the documents in PDF (requires pdflatex [6] to be installed),
use the command:

      $ make latexpdf

If this is successful, the PDF file will be located in
build/latex/ark_guide.pdf.

If pdflatex is not functioning properly, you may instead try

      $ make latex

This will build the raw LaTeX source file build/latex/ark_guide.tex, that
you may then compile into a PS or DVI file as desired.

To remove the build/ directory entirely, or to clean up before
rebuilding the documentation, use the command:

      $ make clean


References:
-----------

[1] http://docutils.sourceforge.net/rst.html
[2] http://sphinx.pocoo.org/
[3] http://www.python.org/
[4] https://github.com/paulromano/sphinx-fortran-extension
[5] https://github.com/ryan-roemer/sphinx-bootstrap-theme
[6] http://www.tug.org/applications/pdftex/
