Add documentation

.gitignore

@@ -4,5 +4,6 @@
 .DS_Store
 
 build/
+_build/
 data/
 reference_code/

.travis.yml

@@ -0,0 +1,17 @@
+language: python
+python: 3.6
+
+install:
+  - pip install -r docs/requirements.txt
+
+script:
+  - sphinx-build -W docs docs/_build
+
+after_success:
+  - if [[ $TRAVIS_BRANCH == 'master' ]]; then
+      export DATE=$(date '+%Y-%m-%d %T');
+      git config --global user.email "[email protected]";
+      git config --global user.name "TravisCI";
+      ghp-import -m "Last update at $DATE" -b gh-pages docs/_build;
+      git push -fq "https://[email protected]/xchoo/spaun2.0.git" gh-pages;
+    fi

README.rst

@@ -0,0 +1,62 @@
+*****
+Spaun
+*****
+
+Spaun is currently the world's largest functional brain model.
+It is the main focus of Chapter 7 of `How to Build a Brain
+<http://www.amazon.com/How-Build-Brain-Architecture-Architectures/dp/0199794545/>`_
+by Chris Eliasmith.
+Spaun first appeared in Science;
+these documents also serve as a home
+to supporting material for the original paper.
+
+The Spaun model consists of about 2.5 million spiking neurons.
+It has a single eye and an arm.
+All input is raw images shown to the eye,
+and all output is arm movements,
+controlled directly by the brain.
+
+.. topic:: Spaun performing several tasks
+
+   .. raw:: html
+
+      <iframe width="100%" height="400" src="https://www.youtube.com/embed/RrxmlbZa7C4" frameborder="0" allowfullscreen></iframe>
+
+This project contains the Spaun [1]_ model,
+updated for Nengo 2.0.
+
+.. [1] Chris Eliasmith, Terrence C. Stewart, Xuan Choo, Trevor Bekolay,
+   Travis DeWolf, Yichuan Tang, and Daniel Rasmussen. A large-scale model
+   of the functioning brain. Science, 338:1202-1205, 2012.
+   doi:10.1126/science.1225266.
+
+Running with Nengo OCL
+======================
+
+If you want to run with ``nengo_ocl``::
+
+  python run_spaun.py -d 512 --ocl --ocl_platform=1 --ocl_device=3
+
+where:
+
+- the ``-d`` flag sets the dimensionality of Spaun,
+- the ``--ocl`` flag tells the run script to use ``nengo_ocl``
+- the --ocl_platform flag tells it what OCL platform to use
+- the --ocl_device flag tells it what ocl device to use on said platform
+  (this flag is optional, it's used in the context creation for pyopencl)
+
+To determine the ``ocl_platform`` and ``ocl_device`` of the device you want to
+use, see ``pyopencl.create_some_context()``.
+
+To enable OCL profiling, find where the ``nengo_ocl.Simulator`` is created
+in ``run_spaun.py``, and uncomment the version that has provifiling enabled.
+Also uncomment the line to print profiling.
+
+Resources
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   videos
+   press

docs/_static/custom.css

@@ -0,0 +1,40 @@
+.MathJax .mi, .MathJax .mo {
+    color: inherit;
+}
+
+.container.docutils {
+    margin: inherit;
+    padding: inherit;
+    width: inherit;
+}
+
+.container.docutils.toggle {
+    margin: 0;
+    padding: 0;
+}
+
+.toggle .header {
+    clear: both;
+    cursor: pointer;
+    display: block;
+}
+
+.toggle .header::after {
+    content: " ▼";
+    display: inline;
+}
+
+.toggle .header.open::after {
+    content: " ▲";
+    display: inline;
+}
+
+img.float-right {
+    float: right;
+    margin-left: 6px;
+    margin-bottom: 6px;
+}
+
+img.flag {
+    margin-bottom: 3px;
+}

docs/_templates/layout.html

@@ -0,0 +1,22 @@
+{# Import the theme's layout. #}
+{% extends "!layout.html" %}
+
+{%- block extrahead %}
+<link rel="stylesheet" type="text/css" href="{{ pathto("_static/custom.css", 1) }}">
+{# Call the parent block #}
+{{ super() }}
+{%- endblock %}
+
+{%- block footer %}
+  <script type="text/javascript">
+    $(document).ready(function() {
+      $(".toggle > *").hide();
+      $(".toggle .header").show();
+      $(".toggle .header").click(function() {
+        $(this).parent().children().not(".header").toggle(400);
+        $(this).parent().children(".header").toggleClass("open");
+      });
+    });
+  </script>
+{{ super() }}
+{%- endblock %}

docs/conf.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+
+from datetime import datetime
+import os
+import sys
+
+import guzzle_sphinx_theme
+
+sys.path.extend(os.path.dirname(__file__))
+extensions = [
+    "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
+    "guzzle_sphinx_theme",
+]
+
+suppress_warnings = ['image.nonlocal_uri']
+source_suffix = ".rst"
+master_doc = "index"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+project = "Spaun"
+copyright = "2015-2017, Applied Brain Research"
+author = "Applied Brain Research"
+version = release = datetime.now().strftime("%Y-%m-%d")
+language = None
+
+todo_include_todos = True
+
+intersphinx_mapping = {
+    "nengo": ("https://www.nengo.ai/nengo", None)
+}
+
+# HTML theming
+pygments_style = "sphinx"
+templates_path = ["_templates"]
+html_static_path = ["_static"]
+
+html_theme_path = guzzle_sphinx_theme.html_theme_path()
+html_theme = "guzzle_sphinx_theme"
+
+html_theme_options = {
+    "project_nav_name": project,
+    "base_url": "https://xchoo.github.io/spaun",
+}
+
+# Other builders
+htmlhelp_basename = project
+
+latex_elements = {
+    # "papersize": "letterpaper",
+    # "pointsize": "11pt",
+    # "preamble": "",
+    # "figure_align": "htbp",
+}
+
+latex_documents = [
+    (master_doc,  # source start file
+     "%s.tex" % project.lower(),  # target name
+     "%s Documentation" % project,  # title
+     author,  # author
+     "manual"),  # documentclass
+]
+
+man_pages = [
+    # (source start file, name, description, authors, manual section).
+    (master_doc, project.lower(), "%s Documentation" % project, [author], 1)
+]
+
+texinfo_documents = [
+    (master_doc,  # source start file
+     project,  # target name
+     "%s Documentation" % project,  # title
+     author,  # author
+     project,  # dir menu entry
+     "Spaun",  # description
+     "Miscellaneous"),  # category
+]

docs/index.rst

@@ -0,0 +1 @@
+.. include:: ../README.rst