.. include:: autodoc_abbr_options_c.rst .. _`sec:documentation`: Documentation ============= |PSIfours| documentation is generated by `Sphinx `_ and lives in :source:`doc/sphinxman`. Installing Sphinx ^^^^^^^^^^^^^^^^^ Installing Sphinx is only necessary to build the documentation yourself, locally. Ultimately, the docs will be served, either from trac or 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-1.14-1.fc15.x86_64 Documentation Structure ^^^^^^^^^^^^^^^^^^^^^^^ Sphinx has nice capabilities for extracting docstrings from python files, presenting both auto generated and explicitly composed 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 Some documentation is even extracted from Psi4 objects at runtime. * PsiMod: docstrings for the PsiMod built-in module constructed in :source:`src/bin/psi4` * DFT: functional availibility and characteristics as encoded in :source:`lib/python/functional.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 `_ * `rendered test document `_ *vs.* `source test document `_ * `Another reStructuredText `_ * `A third reStructuredText and Sphinx `_ * `LaTeX that Sphinx can handle `_ * `Sphinx Docs `_ 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 ``""" comment """`` docstrings in python modules. 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```).