Merge branch 'inf-010' into development

mvousden · mvousden · commit 04c148602029 · 2016-02-28T19:34:18.000Z
Conflicts:
	jobs/provision_virtualmicromagnetics_full.yml
	jobs/provision_virtualmicromagnetics_lite.yml
diff --git a/jobs/provision_virtualmicromagnetics_full.yml b/jobs/provision_virtualmicromagnetics_full.yml
@@ -42,10 +42,12 @@
   roles:
     - other_dependencies
     - oommf
+    - oommf_examples
     - magpar
+    - magpar_examples
     - nmag
+    - nmag_examples
     - fidimag
-    - magpar_oommf_nmag_examples
     - xserver
     - { role: add_super_user, AUTOLOGIN: true }
     - { role: set_hostname, HOSTNAME: virtualmicromagnetics-full }
diff --git a/jobs/provision_virtualmicromagnetics_lite.yml b/jobs/provision_virtualmicromagnetics_lite.yml
@@ -40,10 +40,12 @@
 
   roles:
     - oommf
+    - oommf_examples
     - magpar
+    - magpar_examples
     - nmag
+    - nmag_examples
     - fidimag
-    - magpar_oommf_nmag_examples
     - xserver
     - { role: add_super_user, AUTOLOGIN: true }
     - { role: set_hostname, HOSTNAME: virtualmicromagnetics-lite }
diff --git a/roles/magpar_examples/meta/main.yml b/roles/magpar_examples/meta/main.yml
@@ -0,0 +1,4 @@
+---
+dependencies:
+  - { role: docutils }
+  - { role: magpar }
diff --git a/roles/magpar_examples/tasks/build_documentation.yml b/roles/magpar_examples/tasks/build_documentation.yml
diff --git a/roles/magpar_examples/tasks/magpar_examples.yml b/roles/magpar_examples/tasks/magpar_examples.yml
diff --git a/roles/magpar_examples/tasks/main.yml b/roles/magpar_examples/tasks/main.yml
@@ -0,0 +1,6 @@
+---
+# This Ansible role prepares Magpar examples and places some documentation on
+# the Desktop.
+
+- include: magpar_examples.yml
+- include: build_documentation.yml
diff --git a/roles/magpar_examples/templates/magpar_examples.rst b/roles/magpar_examples/templates/magpar_examples.rst
@@ -0,0 +1,16 @@
+Magpar Examples
+---------------
+
+Examples of magpar are available in a seperate tarball to the one used for
+installing magpar itself. The examples are already prepared on this virtual
+machine (albeit slightly modified), but can be found at::
+
+    ~/magpar-0_9_ex.tar.gz
+
+To run one of these examples, simply navigate to the directory containing the
+example and execute the run command using bash, like so::
+
+    cd ~/magpar-examples/sphere_demag/
+    bash run
+
+This script will produce some output files visible in the directory.
diff --git a/roles/magpar_examples/vars/main.yml b/roles/magpar_examples/vars/main.yml
@@ -7,11 +7,9 @@ MAGPAR_EXAMPLES_URL: http://www.magpar.net/static/magpar/download/{{ MAGPAR_EXAM
 # Examples location
 EXAMPLES_FOLDER: /etc/skel
 MAGPAR_EXAMPLES_FOLDER: "{{ EXAMPLES_FOLDER }}/magpar-0.9/magpar-examples"
-OOMMF_EXAMPLES_FOLDER: "{{ EXAMPLES_FOLDER }}/oommf-oxs-examples"
-NMAG_EXAMPLES_FOLDER: "{{ EXAMPLES_FOLDER }}/nmag-examples"
 
 # Name of the RST template to generate HTML examples from.
-EXAMPLES_RST_FILE: magpar_oommf_nmag_examples.rst
+EXAMPLES_RST_FILE: magpar_examples.rst
 
 # Location to place the HTML documentation.
 EXAMPLES_DOC_FOLDER: "{{ EXAMPLES_FOLDER }}/Desktop"
diff --git a/roles/magpar_oommf_nmag_examples/tasks/main.yml b/roles/magpar_oommf_nmag_examples/tasks/main.yml
diff --git a/roles/magpar_oommf_nmag_examples/templates/magpar_oommf_nmag_examples.rst b/roles/magpar_oommf_nmag_examples/templates/magpar_oommf_nmag_examples.rst
diff --git a/roles/nmag_examples/meta/main.yml b/roles/nmag_examples/meta/main.yml
@@ -1,6 +1,4 @@
 ---
 dependencies:
   - { role: docutils }
-  - { role: oommf }
-  - { role: magpar }
   - { role: nmag }
diff --git a/roles/nmag_examples/tasks/build_documentation.yml b/roles/nmag_examples/tasks/build_documentation.yml
@@ -0,0 +1,23 @@
+- name: Create examples documentation directory.
+  file:
+    name={{ EXAMPLES_DOC_FOLDER }}
+    state=directory
+  sudo: yes
+
+- name: Copy RST examples to examples folder.
+  template:
+    src={{ EXAMPLES_RST_FILE }}
+    dest={{ EXAMPLES_DOC_FOLDER }}/{{ EXAMPLES_RST_FILE }}
+  sudo: yes
+
+- name: Convert documentation to HTML.
+  shell: rst2html.py {{ EXAMPLES_RST_FILE }} Examples.html
+    chdir={{ EXAMPLES_DOC_FOLDER }}
+    creates={{ EXAMPLES_DOC_FOLDER }}/Examples.html
+  sudo: yes
+
+- name: Remove the RST examples file from the examples folder.
+  file:
+    path={{ EXAMPLES_DOC_FOLDER }}/{{ EXAMPLES_RST_FILE }}
+    state=absent
+  sudo: yes
diff --git a/roles/nmag_examples/tasks/main.yml b/roles/nmag_examples/tasks/main.yml
@@ -0,0 +1,6 @@
+---
+# This Ansible role prepares Nmag examples and places some documentation on the
+# Desktop.
+
+- include: nmag_examples.yml
+- include: build_documentation.yml
diff --git a/roles/nmag_examples/tasks/nmag_examples.yml b/roles/nmag_examples/tasks/nmag_examples.yml
diff --git a/roles/nmag_examples/templates/nmag_examples.rst b/roles/nmag_examples/templates/nmag_examples.rst
@@ -0,0 +1,32 @@
+Nmag Examples
+--------
+
+Nmag examples can also be run, and can be found in section 2 (Guided Tour) of
+the manual found here:
+
+    http://nmag.soton.ac.uk/nmag/current/manual/html/manual.html
+
+or locally in:
+
+    `~/nmag-0.2.1/doc/html/manual.html </home/virtualmicromagnetics/nmag-0.2.1/doc/html/manual.html>`__
+
+Example files can be found in::
+
+    ~/nmag-examples/
+
+A test suite is also available for the discerning user. To use the test suite,
+configuration must first be performed::
+
+    sudo su  # We need to run this as root for permissions purposes.
+    cd /opt/nmag/nmag-0.2.1/nsim/tests/config
+    PATH=$PATH:/opt/nmag/nmag-0.2.1/nsim/bin
+    bash find_nsim.sh
+    exit
+
+The tests are wrapped in a Makefile, and hence can only be run after the
+configuration by commanding::
+
+    sudo su
+    cd /opt/nmag/nmag-0.2.1/nsim/tests
+    make
+    exit
diff --git a/roles/nmag_examples/vars/main.yml b/roles/nmag_examples/vars/main.yml
@@ -0,0 +1,9 @@
+# Examples location
+EXAMPLES_FOLDER: /etc/skel
+NMAG_EXAMPLES_FOLDER: "{{ EXAMPLES_FOLDER }}/nmag-examples"
+
+# Name of the RST template to generate HTML examples from.
+EXAMPLES_RST_FILE: nmag_examples.rst
+
+# Location to place the HTML documentation.
+EXAMPLES_DOC_FOLDER: "{{ EXAMPLES_FOLDER }}/Desktop"
diff --git a/roles/oommf_examples/meta/main.yml b/roles/oommf_examples/meta/main.yml
@@ -0,0 +1,4 @@
+---
+dependencies:
+  - { role: docutils }
+  - { role: oommf }
diff --git a/roles/oommf_examples/tasks/build_documentation.yml b/roles/oommf_examples/tasks/build_documentation.yml
@@ -0,0 +1,23 @@
+- name: Create examples documentation directory.
+  file:
+    name={{ EXAMPLES_DOC_FOLDER }}
+    state=directory
+  sudo: yes
+
+- name: Copy RST examples to examples folder.
+  template:
+    src={{ EXAMPLES_RST_FILE }}
+    dest={{ EXAMPLES_DOC_FOLDER }}/{{ EXAMPLES_RST_FILE }}
+  sudo: yes
+
+- name: Convert documentation to HTML.
+  shell: rst2html.py {{ EXAMPLES_RST_FILE }} Examples.html
+    chdir={{ EXAMPLES_DOC_FOLDER }}
+    creates={{ EXAMPLES_DOC_FOLDER }}/Examples.html
+  sudo: yes
+
+- name: Remove the RST examples file from the examples folder.
+  file:
+    path={{ EXAMPLES_DOC_FOLDER }}/{{ EXAMPLES_RST_FILE }}
+    state=absent
+  sudo: yes
diff --git a/roles/oommf_examples/tasks/main.yml b/roles/oommf_examples/tasks/main.yml
@@ -0,0 +1,6 @@
+---
+# This Ansible role prepares OOMMF examples and places some documentation on
+# the Desktop.
+
+- include: oommf_examples.yml
+- include: build_documentation.yml
diff --git a/roles/oommf_examples/tasks/oommf_examples.yml b/roles/oommf_examples/tasks/oommf_examples.yml
diff --git a/roles/oommf_examples/templates/oommf_examples.rst b/roles/oommf_examples/templates/oommf_examples.rst
@@ -0,0 +1,12 @@
+OOMMF Examples
+--------------
+
+OOMMF examples are available from installation, and some can be found in::
+
+    ~/oommf-oxs-examples/
+
+To execute one of these examples, such as standard problem 1, command::
+
+    oommf boxsi ~/oommf-oxs-examples/stdprob1.mif
+
+Astute users may note that oommf may be executed from any directory.
diff --git a/roles/oommf_examples/vars/main.yml b/roles/oommf_examples/vars/main.yml
@@ -0,0 +1,9 @@
+# Examples location
+EXAMPLES_FOLDER: /etc/skel
+OOMMF_EXAMPLES_FOLDER: "{{ EXAMPLES_FOLDER }}/oommf-oxs-examples"
+
+# Name of the RST template to generate HTML examples from.
+EXAMPLES_RST_FILE: oommf_examples.rst
+
+# Location to place the HTML documentation.
+EXAMPLES_DOC_FOLDER: "{{ EXAMPLES_FOLDER }}/Desktop"
