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.
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).
When building the documentation, a number of png-files are generated. For that to work, you need the following installed:
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
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:
: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}\]
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:
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.
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]: yThis 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)
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.
install Vagrant on a host:
on Windows 7:
open command prompt (see http://windows.microsoft.com/en-us/windows/command-prompt-faq) and create the C:ase-develop directory:
cd C:\ase-develop
download the following software under C:ase-develop:
install the downloaded software (you will need to click in order to agree to install the software):
C:\ase-develop>vagrant_1.7.2.msi /passive
C:\ase-develop>putty-0.64-installer.exe /silent
C:\ase-develop>VirtualBox-4.3.26-98988-Win.exe --silent --extract --path .
C:\ase-develop>VirtualBox-4.3.26-98988-MultiArch_amd64.msi /passive
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.
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
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 -.
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"
you can access the documentation webpage from the host with:
$ firefox http://localhost:8080