Merge pull request #64 from futurecore/more-improved-docs

More improved docs

.coveragerc

@@ -25,7 +25,6 @@ exclude_lines =
     # Don't complain about code that only executes when translated.
     .*we_are_translated.*
     def get_printable_location
-    _RevelationByteMemory
 
     # Don't complain about every single status bit.
     self._get_nth_bit_of_register

README.md

@@ -88,6 +88,20 @@ EXAMPLES:
 ```
 
 
+## Revelation features
+
+There are a small number of unimplemented features in Revelation:
+
+  * Breakpoints (both `bkpt` and `mbkpt`)
+  * Multi-core interrupts (`sync` and `wand`)
+  * Floating-point rounding modes (i.e. compiling with `-mfp-mode=int|truncate|round-nearest`)
+  * Direct-memory access
+  * Work-groups and loading more than one binary
+  * The `DEBUGSTATUS` and `DEBUGCMD` registers (you can read and write to these but they don't have any special effects)
+  * The `MESHCONFIG` registers (you can read and write to these but they don't have any special effects)
+  * Event timers other than IALU and FPU valid instructions
+
+
 ## Translating the simulator
 
 'Translating' is the process of converting the RPython code here into C, and then compiling that to a native executable.
@@ -113,34 +127,16 @@ If you want your compiled Revelation simulator to be able to write out a trace o
 Please report any problems you have with Revelation on the [Issues page](https://github.com/futurecore/revelation/issues).
 
 To contribute to Revelation itself, please fork this repository and raise a Pull Request, and if it is relevant to your changes please include unit tests.
-Translating Revelation will be relatively slow, so it is easiest to run and test the simulator un-translated, until your changes are stable, e.g.:
+Translating Revelation will be relatively slow, so it is easiest to run and test the simulator un-translated, until your changes are stable.
 
-```bash
-$ pypy revelation/sim.py revelation/test/c/hello.elf
-Loading program revelation/test/c/hello.elf on to core 0x808 (32, 08)
-Hello, world!
-Done! Total ticks simulated = 1951
-Core 0x808 (32, 08): STATUS=0x00000005, Instructions executed=1951
-```
+Details of how the Revelation code is structured, how the unit tests work and other internals are available in the [online documentation](https://readthedocs.org/projects/revelation/latest/contributing.html).
 
 To work with the code here you need a copy of Pydgin, which you can obtain a copy from the [Pydgin project page](https://github.com/cornell-brg/pydgin).
 Pydgin is a framework for writing functional simulators as [just in time interpreters](https://en.wikipedia.org/wiki/Just-in-time_compilation).
-You can read more about it in this paper:
 
-> Derek Lockhart, Berkin Ilbeyi, and Christopher Batten. (2015) Pydgin: Generating Fast Instruction Set Simulators from Simple Architecture Descriptions with Meta-Tracing JIT Compilers. IEEE International Symposium on Performance Analysis of Systems and Software (ISPASS). Available at: http://csl.cornell.edu/~cbatten/pdfs/lockhart-pydgin-ispass2015.pdf
-
-
-### Running unit tests
-
-To run the Revelation unit tests, ensure that the required packages are installed:
+You can read more about Pydgin in this paper:
 
-    $ pip install -r requirements.txt
-
-Then run the tests themselves:
-
-    $ py.test --cov-report term-missing --cov revelation revelation/test/
-
-Note that the tests may take some time to run, particularly those that load an ELF file.
+> Derek Lockhart, Berkin Ilbeyi, and Christopher Batten. (2015) Pydgin: Generating Fast Instruction Set Simulators from Simple Architecture Descriptions with Meta-Tracing JIT Compilers. IEEE International Symposium on Performance Analysis of Systems and Software (ISPASS). Available at: http://csl.cornell.edu/~cbatten/pdfs/lockhart-pydgin-ispass2015.pdf
 
 
 ## License

docs/_getversionstrings.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python
+
+import subprocess
+
+def get_version_string():
+    tags = subprocess.check_output(['git', 'tag'])
+    if tags:
+        tag_list = sorted(tags.strip().split('\n'))
+        return tag_list[-1]
+    return 'pre-release'
+
+def get_minor_version_string():
+    return '.'.join(get_version_string().split('.')[:2])
+
+if __name__ == '__main__':
+    print get_minor_version_string()

docs/_templates/globaltoc.html

@@ -0,0 +1,12 @@
+<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+
+<ul>
+  <li><a href="{{ pathto('index') }}">Home</a></li>
+  <li><a href="{{ pathto('quickstart') }}">Quickstart</a></li>
+  <li><a href="{{ pathto('contributing') }}">Contributing</a></li>
+</ul>
+
+{%- if display_toc %}
+  <hr>
+  {{ toc }}
+{%- endif %}

docs/_templates/links.html

@@ -0,0 +1,11 @@
+<h3>Useful Links</h3>
+<ul>
+  <li><a href="{{ pathto('index') }}">Revelation documentation</a></li>
+  <li><a href="{{ pathto('contributing') }}">Contribution Guide</a></li>
+  <li><a href="https://github.com/futurecore/revelation/">Revelation @GitHub</a></li>
+  <li><a href="https://github.com/futurecure/revelation/issues">Issue Tracker</a></li>
+  <li><a href="http://www.adapteva.com/epiphanyiii/">Epiphany III</a></li>
+  <li><a href="http://www.adapteva.com/epiphanyiv/">Epiphany IV</a></li>
+  <li><a href="http://adapteva.com/docs/epiphany_arch_ref.pdf">Epiphany Architecture Reference</a></li>
+</ul>
+

docs/_templates/sidebarintro.html

@@ -0,0 +1,4 @@
+<h3>About Revelation</h3>
+<p>
+Revelation is a just-in-time ISS simulator for the Adapteva Epiphany architecture.
+</p>

docs/_themes/.gitignore

@@ -0,0 +1,3 @@
+*.pyc
+*.pyo
+.DS_Store

docs/_themes/LICENSE

@@ -0,0 +1,37 @@
+Copyright (c) 2010 by Armin Ronacher.
+
+Some rights reserved.
+
+Redistribution and use in source and binary forms of the theme, with or
+without modification, are permitted provided that the following conditions
+are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above
+  copyright notice, this list of conditions and the following
+  disclaimer in the documentation and/or other materials provided
+  with the distribution.
+
+* The names of the contributors may not be used to endorse or
+  promote products derived from this software without specific
+  prior written permission.
+
+We kindly ask you to only use these themes in an unmodified manner just
+for Flask and Flask-related products, not for unrelated projects.  If you
+like the visual style and want to use it for your own projects, please
+consider making some larger changes to the themes (such as changing
+font faces, sizes, colors or margins).
+
+THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

docs/_themes/README

@@ -0,0 +1,31 @@
+Flask Sphinx Styles
+===================
+
+This repository contains sphinx styles for Flask and Flask related
+projects.  To use this style in your Sphinx documentation, follow
+this guide:
+
+1. put this folder as _themes into your docs folder.  Alternatively
+   you can also use git submodules to check out the contents there.
+2. add this to your conf.py:
+
+   sys.path.append(os.path.abspath('_themes'))
+   html_theme_path = ['_themes']
+   html_theme = 'flask'
+
+The following themes exist:
+
+- 'flask' - the standard flask documentation theme for large
+  projects
+- 'flask_small' - small one-page theme.  Intended to be used by
+  very small addon libraries for flask.
+
+The following options exist for the flask_small theme:
+
+   [options]
+   index_logo = ''              filename of a picture in _static
+                                to be used as replacement for the
+                                h1 in the index.rst file.
+   index_logo_height = 120px    height of the index logo
+   github_fork = ''             repository name on github for the
+                                "fork me" badge

docs/_themes/flask/layout.html

@@ -0,0 +1,24 @@
+{%- extends "basic/layout.html" %}
+{%- block extrahead %}
+  {{ super() }}
+  {% if theme_touch_icon %}
+  <link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
+  {% endif %}
+  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
+{% endblock %}
+{%- block relbar2 %}{% endblock %}
+{% block header %}
+  {{ super() }}
+  {% if pagename == 'index' %}
+  <div class=indexwrapper>
+  {% endif %}
+{% endblock %}
+{%- block footer %}
+  <div class="footer">
+    &copy; Copyright {{ copyright }}.
+    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
+  </div>
+  {% if pagename == 'index' %}
+  </div>
+  {% endif %}
+{%- endblock %}

docs/_themes/flask/relations.html

@@ -0,0 +1,19 @@
+<h3>Related Topics</h3>
+<ul>
+  <li><a href="{{ pathto(master_doc) }}">Documentation overview</a><ul>
+  {%- for parent in parents %}
+  <li><a href="{{ parent.link|e }}">{{ parent.title }}</a><ul>
+  {%- endfor %}
+    {%- if prev %}
+      <li>Previous: <a href="{{ prev.link|e }}" title="{{ _('previous chapter')
+        }}">{{ prev.title }}</a></li>
+    {%- endif %}
+    {%- if next %}
+      <li>Next: <a href="{{ next.link|e }}" title="{{ _('next chapter')
+        }}">{{ next.title }}</a></li>
+    {%- endif %}
+  {%- for parent in parents %}
+  </ul></li>
+  {%- endfor %}
+  </ul></li>
+</ul>