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

In this directory and below are the ARKode examples 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 [5] to be installed),
use the command: 

      $ make latexpdf

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

If pdflatex is not functioning properly, you may instead try

      $ make latex

This will build the raw LaTeX source file
build/latex/ARKode_examples.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_example.tex will differ from the version
distributed with SUNDIALS (sundials/doc/arkode/ARKode_example.tex).
These discrepancies may be fixed using standard merge tools.  In this
merging process, one code block in
sundials/doc/arkode/ARKode_example.tex is included within the region: 

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

This should remain unchanged in sundials/doc/arkode/ARKode_example.tex
(unless updating the version numbers), whereas all other changes
should be ported from build/latex/ARKode_example.tex directly into
sundials/doc/arkode/ARKode_example.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/ryan-roemer/sphinx-bootstrap-theme
[5] http://www.tug.org/applications/pdftex/
