Documentation¶
PSI4’s documentation is generated by Sphinx and lives in psi4/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-1.14-1.fc15.x86_64
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. PSI4’s 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: psi4/include/physconst.h
- Python Driver: docstrings from *.py files in psi4/lib/python
- Databases: docstrings from *.py files in psi4/lib/databases
- Basis Sets: *.gbs files in psi4/lib/basis
- C++ Keywords: psi4/src/bin/psi4/read_options.cc
- Sample Inputs: input.dat files in psi4/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 psi4/src/bin/psi4
- DFT: functional availibility and characteristics as encoded in psi4/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 psi4/doc/sphinxman/Makefile.in , so very long builds should be infrequent (unless you’re touching psi4/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.
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
psi4/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
^ $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:`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 psi4/doc/sphinxman/source/template_appendices.rst for an appendix or to psi4/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 psi4/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 psi4/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 psi4/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 psi4/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.