Instructions to build the DIALS documentation pages using sphinx
================================================================

Pre-requisites:

i)  you have the dials.github.io repository cloned in your modules directory:

   $ git clone git@github.com:dials/dials.github.io.git

ii) you have sphinx and dependencies (docutils, etc.) installed in your
    cctbx.python.

iii) Install biopython if you don’t already have it (this is to populate the
   publications section):

   $ libtbx.python -m pip install biopython

iv) Get the alabaster sphinx theme:

   $ libtbx.python -m pip install alabaster

To update the DIALS webpages:

1) Update the dials.github.io:

  $ git pull --rebase

2) Make changes to the .rst files in dials/doc/sphinx. Commit the resulting
   changes to the .rst files to the dials repository (ideally after running
   steps 3 & 4 to visually inspect the generated html files).

3) Build the documentation using the dev.dials.make_sphinx_html command which
   builds the sphinx documentation and copies the output into the
   dials.github.io.git directory.

   $ dev.dials.make_sphinx_html

4) View the documentation! e.g. on mac:

   $ open $(libtbx.find_in_repositories dials.github.io)/index.html

5) Either (i) commit the resulting changes to the dials.github.io repository to
   make modifications immediately available or (ii) wait for the next Jenkins
   job to re-build the website (this happens nightly UK time). If you choose not
   to commit your local changes, you might want to run the following git
   commands (in the dials.github.io source directory) which reset the local
   changes to the dials.github.io repository and remove untracked
   files/directories, before running any future git pull commands:

   $ git checkout . ; git clean -f -d