Writing documentation

We use the Sphinx tool to generate the documentation. The documentation is stored on GitLab as text files in the doc directory using the reStructuredText markup language.

Installing Docutils and Sphinx

If you do:

$ pip install sphinx_rtd_theme --user

and add ~/.local/bin to you PATH environment variable, then you should be ready to go. You may need the following installed, but they are not required: scipy, matplotlib, povray, dvipng, pdflatex, bibtex, AUCTex, fontconfig, convert (ImageMagick).

Using Sphinx

First, you should take a look at the documentation for Sphinx and reStructuredText.

If you don’t already have your own copy of the ASE package, then read here how to get everything set up.

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

$ cd ~/ase/doc
$ make

This might take a long time the first time you do it.

Note

Make sure that you build the Sphinx documentation using the corresponding ASE version by setting the environment variables PYTHONPATH and PATH.

Create a branch for your work, make your changes to the .rst files, run make again, check the results and if things look ok, create a merge request:

$ git checkout -b fixdoc
$ idle index.rst
$ make
$ make browse
$ git commit -am "..."
$ git push -u origin fixdoc

Extensions to Sphinx

We have a couple of extensions to Sphinx:

:mol:

Use :mol:`CH_3OH` to get CH₃OH.

:git:

A role for creating a link to a file on GitLab. If you write :git:`ase/atoms.py`, you will get: ase/atoms.py.

:math:

This role is for inline LaTeX-style math. Example: :math:`\sin(x_n^2)` gives you \(\sin(x_n^2)\). This role is actually the default for ASE’s documentation, so you should leave out the :math: part like here: `\sin(x_n^2)`.

.. math::

Write displayed LaTeX-style math. Example:
.. math:: \frac{1}{1+x^2}
gives you:

\[\frac{1}{1+x^2}\]

Running Python code to create figures

If you want to include a picture in your page, you should not check in the png-file to our Git repositoy! Instead, you should check in the Python script you used to generate the picture (you can also generate csv-files or pdf-files like this). The first line of the script should look like this:

# creates: fig1.png, fig2.png, table1.csv

Sphinx will run the script and generate the files that you can then use in your rst-file. Examples:

reStructedText in emacs

For people using emacs, the reStructuredText extension is highly recommended. The intallation procedure is described in the top of the file, but for most people, it is enough to place it in your emacs load-path (typically .emacs.d/) and add the lines:

(add-to-list 'load-path "~/.emacs.d")
(require 'rst)

somewhere in your .emacs file.

To make the mode auto load for relevant file extension, you can write something like:

(setq auto-mode-alist
      (append '(("\\.rst$" . rst-mode)
                ("\\.rest$" . rst-mode)) auto-mode-alist))

In your .emacs file.