ARKode Documentation README
=============================

In this directory and below are the ARKode documentation. They 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/ARKode.pdf.  

If pdflatex is not functioning properly, you may instead try

      $ make latex

This will build the raw LaTeX source file build/latex/ARKode.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



Merging the documentation up to the main SUNDIALS versions:
-----------------------------------------------------------

After running 'make latexpdf' above, the file build/latex/ARKode.tex
will differ from the version distributed with SUNDIALS
(sundials/doc/arkode/ARKode.tex).  These discrepancies may be fixed
using standard merge tools.  In this merging process, two code blocks
in sundials/doc/arkode/ARKode.tex are included within the regions:

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   %%% MANUALLY ADDED/EDITED
   text
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

These should remain unchanged in sundials/doc/arkode/ARKode.tex
(unless updating the version numbers), whereas all other changes
should be ported from build/latex/ARKode.tex directly into
sundials/doc/arkode/ARKode.tex with no modification.


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/
