Writing documentation

We use the Sphinx tool to generate the documentation (both HTML and PDF). The documentation is stored in SVN as text files in the doc directory using the reStructuredText markup language.

Installing Docutils and Sphinx

If you prefer to configure Sphinx in a vitual machine see Setting up development environment with Vagrant.

The reStructuredText parser that Sphinx needs, is part of the Docutils project. So, we need to install docutils and sphinx (version>= 1.1.3).

Other requirements

When building the documentation, a number of png-files are generated. For that to work, you need the following installed:

  • scipy
  • matplotlib
  • epydoc
  • povray (optional)
  • 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 get the Latest development release and install it.

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.

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

$ emacs index.rst
$ make
$ firefox build/html/index.html
$ svn ci -m "..." index.rst

To build a pdf-file, you do this:

$ make latex

Extensions to Sphinx

We have a couple of extensions to Sphinx:

:mol:

Use :mol:`CH_3OH` to get CH3OH.

:svn:

A role for creating a link to a file in SVN. If you write :svn:`ase/atoms.py`, you will get: ase/atoms.py.

:trac:

A role for creating a link to a file in Trac. If you write :trac:`ase/atoms.py`, you will get: ase/atoms.py.

:epydoc:

A role for creating a link to the API-documentation generated with epydoc. If you write :epydoc:`ase.atoms.Atoms`, you will get: Atoms.

: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 can 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 SVN 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.

Updating Sphinx

Starting a new project with sphinx requires an initial configuration. This is achieved by running sphinx-quickstart. When updating from a very old sphinx you may consider generating new configuration files and updating the old files accordingly.

Note that the current project is configured up-to-date, so if you are “simply” writing the documentation you must skip the sphinx-quickstart step and focus on Using Sphinx.

Here is how do you setup the GPAW project with sphinx:

  • cd to the doc directory,

  • run sphinx-quickstart and answer the questions (example given for GPAW):

    > Root path for the documentation [.]:
    
    > Separate source and build directories (y/N) [n]:
    
    > Name prefix for templates and static dir [.]: _
    
    > Project name: GPAW
    > Author name(s): 2008, CAMd et al.
    
    > Project version: 0.5
    > Project release [0.5]:
    
    > Source file suffix [.rst]:
    
    > Name of your master document (without suffix) [index]: contents
    
    > autodoc: automatically insert docstrings from modules (y/N) [n]: y
    > doctest: automatically test code snippets in doctest blocks (y/N) [n]:
    > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
    

    This will create doc/conf.py and doc/contents.rst. Both these files need to be edited further (doc/conf.py may for example include options for sphinx.ext.pngmath)

Setting up development environment with Vagrant

If you contribue documentation together with the code and tests (and you should) here is how you create a development enviroment on a virtual CentOS7 guest machine using Vagrant. It takes about 10 minutes.

  1. install Vagrant on a host:

    • on Windows 7:

      See https://github.com/Varying-Vagrant-Vagrants/VVV/wiki/Connect-to-Your-Vagrant-Virtual-Machine-with-PuTTY for configuring putty for Vagrant.

      The machine should reboot.

    • on Ubuntu/Debian:

      • install virtualbox dependencies and vagrant:

        $ sudo apt-get install -y vagrant
        
      • add the unprivileged user to the \(vboxusers\) group:

        $ whoami=`whoami`&& sudo usermod -a -G vboxusers $whoami
        
    • on Fedora/RHEL/CentOS:

      • on RHEL6/CentOS6 only: install virtualbox and EPEL repositories:

        $ su -c "yum -y install wget"
        $ su -c "wget http://download.virtualbox.org/virtualbox/rpm/rhel/virtualbox.repo -O /etc/yum.repos.d/virtualbox.repo"
        $ su -c "yum -y install http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm"
        
      • on Fedora only: install virtualbox repository:

        $ su -c "yum -y install wget"
        $ su -c "wget http://download.virtualbox.org/virtualbox/rpm/fedora/virtualbox.repo -O /etc/yum.repos.d/virtualbox.repo"
        
      • install virtualbox dependencies and vagrant:

        $ su -c "yum -y install kernel kernel-devel kernel-headers dkms"
        $ su -c "yum -y install https://dl.bintray.com/mitchellh/vagrant/vagrant_1.7.2_x86_64.rpm"
        

      Reboot in order to get the latest kernel.

      • install virtualbox and add the unprivileged user to the \(vboxusers\) group:

        $ su -c "yum -y install VirtualBox-4.3"
        $ whoami=`whoami`&& su -c "usermod -a -G vboxusers $whoami"
        

    Logout and login in order for the user to get the \(vboxusers\) group permissions.

  2. as the unprivileged user, create the virtual guest:

    $ cd /tmp
    $ mkdir ase-develop
    $ cd ase-develop
    $ wget https://svn.fysik.dtu.dk/projects/ase/trunk/doc/development/Vagrantfile
    $ vagrant up
    $ vagrant ssh -- -X
    
  3. after you log in into the virtual guest in order to build ASE documentation do:

    $ cd /vagrant
    $ svn co https://svn.fysik.dtu.dk/projects/ase/trunk ase
    $ cd ase/doc
    $ PATH=/vagrant/ase/tools:$PATH PYTHONPATH=/vagrant/ase make
    

Note

The ASE checkout is available on the host under /tmp/ase-develop/ase and on the guest under /vagrant/ase. If you need root access on the virtual guest do: sudo su -.

  1. deploy just built documentation into the virtual guest webserver:

    $ su -c "cp -rpf /vagrant/ase/doc/build/html /var/www"
    $ su -c "chown -R apache.apache /var/www/html"
    $ su -c "systemctl reload httpd.service"
    
  2. you can access the documentation webpage from the host with:

    $ firefox http://localhost:8080