Writing documentation

We use the Sphinx tool to generate the GPAW documentation.

First, you should take a look at the documentation for Sphinx and reStructuredText. Also, read carefully the Writing documentation for ASE page.

Getting started

If you don’t already have your own copy of the GPAW package, then perform a Developer installation.

Then cd to the doc directory and build the html-pages:

$ cd ~/gpaw/doc
$ make

Note

Make sure that you build the Sphinx documentation using the corresponding GPAW version by setting the environment variables PYTHONPATH, PATH (described at Developer installation) and the location of setups (described at Installation of PAW datasets).

Make your changes to the .rst files, run the make command again, check the results and if things looks ok, commit:

$ emacs index.rst
$ make
$ firefox build/html/index.html
$ git add index.rst
$ git commit -m "..."

Adding figures and tables

We don’t want to have png and csv files committed to Git. Instead, you should add the Python scripts that generate the figures and table data so that we can always generate them again if needed.

For quick scripts (no more than 5 seconds), see Running Python code to create figures. For more expensive scripts you can use AGTS for running long jobs that create figures or table data for this web-page. For an example, look at the source code here which will produce this: Tutorial: STM images - Al(111).