
.. include:: autodoc_abbr_options_c.rst

.. _`sec:documentation`:

Documentation
=============

|PSIfours| documentation is generated by `Sphinx <http://sphinx.pocoo.org/>`_
and lives in :source:`doc/sphinxman`. It is available online at
`<http://sirius.chem.vt.edu/psi4manual/latest/index.html>`_
for the latest public release and at 
`<http://sirius.chem.vt.edu/psi4manual/master/index.html>`_
for the latest development branch (not all links may be publically
accessible).

Installing Sphinx
^^^^^^^^^^^^^^^^^

Installing Sphinx is only necessary to build the documentation 
yourself, locally. The docs are served from
from trac and psicode, so most users/developers won't need Sphinx 
installed. Nevertheless, installation is easy.

On Mac::

    >>> easy_install sphinx

On Linux:

* Download ::

   >>> curl -O http://pypi.python.org/packages/source/S/Sphinx/Sphinx-1.1.3.tar.gz

* Unpack, etc.
* Build and Install ::

   >>> python setup.py build
   >>> sudo python setup.py install

* Check the path ::

   >>> which sphinx-build
   >>> which latex
   >>> which dvipng

* LaTeX and dvipng are needed to render math. If the latter is missing,
  the following may work. ::

   >>> sudo yum install dvipng

Documentation Structure
^^^^^^^^^^^^^^^^^^^^^^^

Sphinx has nice capabilities for extracting docstrings from python files,
presenting both auto-generated and narrative documentation in
the same format, hyperlinking within and to trac/external websites, and
generating documentation in different formats from the same source.
|PSIfours| documentation is a unified document covering information for
both users and programmers, with different portions served up depending on
the target audience. To this end, one can navigate to ``$(OBJDIR)/doc/sphinxman``
and build the following targets.::

    >>> make help  # to see options
    >>> make       # to build html

    >>> make html
    >>> make html-user
    >>> make html-prog
    >>> make latexpdf-user 
    >>> make latexpdf-prog

This will build the following files, respectively. ::

    build/html/index.html
    build/html-user/index.html
    build/html-prog/index.html
    build/latex-prog/psi4_userman.pdf
    build/latex-prog/psi4_progman.pdf
    
Much of the documentation is auto-generated from the source. At present,
this covers:

* Physical Constants: :source:`include/physconst.h`
* Python Driver: docstrings from \*.py files in :source:`lib/python`
* Databases: docstrings from \*.py files in :source:`lib/databases`
* Basis Sets: \*.gbs files in :source:`lib/basis`
* C++ Keywords: :source:`src/bin/psi4/read_options.cc` 
* Sample Inputs: input.dat files in :source:`samples`
* PSI Variables: ``Process::environment.globals`` lines and comments in the C++ code
* Plugins: ``doc.rst`` text, \*.py modules, and C++ keywords in ``psi4/tests/plugin_*`` plugin directories (disabled at the moment)
* PSI Files: scratch file names and numbers in :source:`include/psifiles.h`

Some documentation is even extracted from Psi4 objects at runtime.

* psi4: docstrings for the psi4 built-in module constructed in :source:`src/bin/psi4`
* DFT: functional availibility and characteristics as encoded in :source:`lib/python/functional.py`
* BasisFamily: fitting basis sets for each orbital basis as encoded in :source:`lib/python/basislistdunning.py` and :source:`lib/python/basislistother.py`

Run ``make help`` to see choices for cleaning various stages of the build.
Running ``make realclean`` clears out the built documentation. Building
all the documentation takes ~10 minutes. There is now good
dependency structure built into the :source:`doc/sphinxman/Makefile.in` ,
so very long builds should be infrequent (unless you're touching :source:`src/bin/psi4/read_options.cc`.
Note that not all dependencies
are encoded (PSI variables, for instance, depend on every .cc file in the
source tree), so for a definitive doc build, run ``make realclean`` and
start from scratch.

reStructuredText
^^^^^^^^^^^^^^^^

Sphinx files are written in reStructuredText (\*.rst). In the html
documentation, source code is available from the sidebar. Here're a
few resources on Sphinx formatting.

* `reStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
* `rendered test document <http://docutils.sourceforge.net/test/functional/expected/standalone_rst_html4css1.html>`_
  *vs.* `source test document <http://svn.python.org/projects/external/docutils-0.5/docs/user/rst/demo.txt>`_
* `Another reStructuredText <http://people.ee.ethz.ch/~creller/web/tricks/reST.html>`_
* `A third reStructuredText and Sphinx <http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html>`_
* `LaTeX that Sphinx can handle <ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf>`_
* `Sphinx Docs <http://sphinx.pocoo.org/contents.html>`_

Math in the Codebase
^^^^^^^^^^^^^^^^^^^^

It is often useful to have mathematical expressions in docstrings or
comments in the code that are auto-documented into the manual. Such
locations include the ``#! comment`` comments at the top of test case
input files, the ``/*- comment -*/`` comments in
:source:`src/bin/psi4/read_options.cc`, and the ``r""" comment """``
docstrings in python modules. (That ``r"""`` makes the string read
literally, so your LaTeX symbols aren't confused with escape characters.)
For the two former, math has traditionally
been written in LaTeX (with the special substitution ``@@`` for
subscripting underscore). The autodoc script has been trained to convert
inline LaTeX math to reST math, provided the expression within dollar
signs is offset from other text. That is, expressions of the form
:regexp:`^ $latex math$[., ]$` (pseudo-regex) are good, while ``H$_2$O`` and LaTeX tables
are not translated correctly. Python docstrings are absorbed as-is, so
please use reST math formatting (essentially ``$latex math$`` :math:`\Rightarrow`
``:math:`latex math```).

The Map of the Sphinx
^^^^^^^^^^^^^^^^^^^^^

* Adding a new Appendix or First-TOC-Level page

  Create your reST file and fill it with information. Add the name of your
  file to :source:`doc/sphinxman/source/template_appendices.rst` for an
  appendix or to :source:`doc/sphinxman/source/template_index.rst` for a
  first-TOC-level.  Consider the ``#####`` lines to be like preprocessor
  directives that separate user and programmer manuals. Finally, add your
  file to the ``STATICDOC`` variable in the Makefile at
  :source:`doc/sphinxman/Makefile.in`. Sphinx will now build with your new
  page.

* Adding a new module to "Theoretical Methods"

  Copy the file of a well-established module, like
  :source:`doc/sphinxman/source/sapt.rst`. Change the title, author, sec
  label, ref, and source labels at the top of the file to point instead to
  your code. Edit :source:`doc/sphinxman/source/methods.rst` to add the
  name of your file so that it will appear in the TOC tree. Add your file
  to the ``STATICDOC`` variable in the Makefile at
  :source:`doc/sphinxman/Makefile.in`. Sphinx will now build with your new
  file.  Follow the models in existing methods pages to write your
  documentation. If you don't get all the keyword links, bibliography
  links, sample inputs, math, tables, etc. working in Sphinx, don't worry
  about it. A genie will probably come through and tidy up all your
  source.

