Tweaked the tutorial, and updated the README to refer to it.

README.rst

@@ -15,113 +15,23 @@ What it does:
 
 * Provides an API to let you programmatically create Java class files.
 
-* Compiles a Python 3.4 source file into a Java class file in a nominated
-  package. Supports the conversion of:
+* Compiles Python 3.4 source files into Java class files, enabling you to run
+  Python code on a JVM (including Android's VM).
 
-  * Class definition and construction
+It isn't a *completely* compliant Python 3.4 implementation - there are some
+language features (like generators and context managers) that still need to be
+implemented, and there is only a bare bones standard library implementation.
+However, it is possible to convert simple Python programs, and even write
+simple Android applications.
 
-  * Class instantiation
+Tutorial
+--------
 
-  * Method definition and invocation
+To take VOC for a spin, run through the `Getting Started guide`_, then start
+with `the first tutorial`_.
 
-  * Some mathematical operations
-
-  * Some operations and methods on primitive types
-
-  * Exception handling
-
-  * for/while/if constructs
-
-  * Identification of mainline entry points
-
-  * Static initialization of modules.
-
-  * List comprehensions
-
-  * Keyword arguments
-
-  * `import`, `from X import Y` and `from X import *` statements for Python code
-
-  * Subclassing Python classes
-
-  * Importing and using native Java APIs
-
-  * Implementing Java interfaces.
-
-  * Extending Java classes.
-
-It *doesn't* currently support (this list is incomplete):
-
-* Generators
-
-* with statements
-
-* ``exec()`` and ``eval()``
-
-These things are all *possible* - it's just a matter of time
-and development effort. The order listed here is a rough indicator of
-development priorities.
-
-Quickstart
-----------
-
-Using Python 3.4, install ``voc``, then run it over your python script::
-
-    $ pip install voc
-    $ python -m voc path/to/your/example.py
-    Creating class 'example'...
-    Writing example/__init__.class...
-    Done.
-
-This will produce an ``__init__.class``, in the ``python/example`` namespace,
-that you can run on any Java 1.7+ VM. To run the classfile, you'll need the
-Python support libraries. These will eventually be available as a download;
-for now, you'll need to compile them. See below for compilation instructions.
-
-Once you've got the support Jarfile, you can run the example.class ensuring that
-the support jarfile is in your classpath. For example, using the Oracle Java VM,
-you would run::
-
-    $ java -XX:-UseSplitVerifier -classpath dist/python-java.jar:. python.example.__init__
-    Hello, World
-
-The ``-XX:-UseSplitVerifier`` argument is necessary to turn off stack map
-verification in Java 7. This could be addressed by computing stack maps
-for generated code.
-
-NOTE: If you are using Java 8, substitute ``-noverify`` in place of ``-XX:-UseSplitVerifier``.
-
-Compiling the support library
------------------------------
-
-Oracle Java
-~~~~~~~~~~~
-
-To compile the Python support libraries for Java (the Oracle JVM)::
-
-    $ ant java
-
-This will create a ``dist`` directory that contains ``python-java.jar``.
-
-Android
-~~~~~~~
-
-To compile for Android, you'll need to `download the Android SDK`_. You only
-need the standalone SDK (see "Other install options") - you don't have to
-download the fully Android Studio if you don't want to.
-
-Once you've downloaded and installed the SDK, create a ``local.properties``
-in the top level ``voc`` project directory, containing a single line::
-
-    sdk.dir=<path to SDK>/sdk
-
-You can then run ``ant`` to compile ``dist/python-android.jar``::
-
-    $ ant android
-
-You can then add ``dist/python-android.jar`` to your Android project.
-
-.. _download the Android SDK: https://developer.android.com/sdk/index.html
+.. _Getting Started guide: http://voc.readthedocs.org/en/latest/intro/getting-started.html
+.. _the first tutorial: http://voc.readthedocs.org/en/latest/tutorials/tutorial-0.html
 
 Documentation
 -------------

docs/index.rst

@@ -1,8 +1,7 @@
 VOC
 ===
 
-.. image:: https://travis-ci.org/pybee/voc.svg?branch=master
-    :target: https://travis-ci.org/pybee/voc
+.. image:: _static/logo.png
 
 **VOC is an early alpha project. If it breaks, you get to keep all the shiny pieces.**
 

docs/intro/getting-started.rst

@@ -1,47 +1,46 @@
 Getting Started
 ===============
 
-In this guide we will walk you through setting up your VOC environment for 
-development and testing. We will assume that you have a working JDK and
-Apache ANT installation and use virtualenv. 
+In this guide we will walk you through setting up your VOC environment for
+development and testing. We will assume that you have a working Python 3, JDK,
+Apache ANT installation and use virtualenv.
 
-Git a copy of pybee/voc
------------------------
-The first step is to fork voc by going to https://github.com/pybee/voc and 
-pressing the fork button at the top. 
+Get a copy of VOC
+-----------------
 
-You are now ready to clone voc by typing in 
+The first step is to create a project directory, and clone VOC:
 
 .. code-block:: bash
 
-    git clone https://github.com/YOUR_ACCOUNT/voc.git
+    $ mkdir tutorial
+    $ cd tutorial
+    $ git clone https://github.com/pybee/voc.git
 
-Setup VOC
----------
-At this point you are ready to setup your isolated voc environment. To do this
-you will need to do the following from the root voc directory
+Then create a virtual environment and install VOC into it:
 
 .. code-block:: bash
 
-    $ virutalenv -p $(which python3) voc
-    $ . voc/bin/activate
+    $ virtualenv -p $(which python3) env
+    $ . env/bin/activate
     $ pip install -e .
 
-
-Building The Support Jar File
+Building the support JAR file
 -----------------------------
-The last thing we need to do is build the python support file. This can be done
-by typing in the following from the VOC root directory
+
+Next, you need to build the Python support file:
 
 .. code-block:: bash
-    
-    $ ant java 
-    
-This should create a dist/python-java.jar file. This will be used when 
-executing the java class that gets compilied. 
 
+    $ cd voc
+    $ ant java
+
+This should create a `dist/python-java.jar` file. This JAR file is a support library
+that implements Python-like behavior and provides the Python standard library for
+the Java environment. This JAR file must be included on the classpath for any
+VOC-generated project.
 
 Next Steps
 ----------
-At this point you are ready to begin your development. A good next step would 
-be to read the `tutorials-0 <https://github.com/pybee/voc/blob/master/docs/tutorials/tutorial-0.rst>`_. 
+
+You now have a working VOC environment, so you can :doc:`start the first
+tutorial </tutorials/tutorial-0>`.

docs/tutorials/tutorial-0.rst

@@ -1,57 +1,64 @@
 Tutorial 0 - Hello, world!
 ==========================
 
-.. _getting-started: https://github.com/pybee/voc/blob/master/docs/intro/getting-started.rst
-
 In this tutorial, you'll take a really simple "Hello, world!" program written in
 Python, convert it into a classfile, and run it on the Java Virtual Machine.
 
 Setup
 -----
 
 This tutorial assumes you've read and followed the instructions in
-getting-started_. If you've done this, you should have:
+:doc:`/intro/getting-started`. If you've done this, you should have:
 
-* Java 7 installed and available on your path
-* A activated Python 3.4 virtual environment
-* `voc` installed in that virtual environment
+* Java 7 installed and available on your path,
+* A ``tutorial`` directory with a VOC checkout,
+* A activated Python 3.4 virtual environment,
+* VOC installed in that virtual environment,
+* A compiled VOC support library.
 
 Start a new project
 -------------------
-Lets start by creating a file called example.py. Inside of this example file
-lets add the following python code
+
+Lets start by creating a ``tutorial0`` directory:
+
+.. code-block:: python
+
+    $ mkdir tutorial0
+    $ cd tutorial0
+
+Then create a file called ``example.py`` in this directory.
+Add the following Python code to ``example.py``:
 
 .. code-block:: python
 
-  print("Hello World!)
-	
-now lets save the file. We will now compile the class
+    print("Hello World!")
+
+Save the file. Run VOC over this file, compiling the Python code into a Java
+class file:
 
 .. code-block:: bash
 
-    $ python -m voc path/to/your/example.py
-    
-you will see output like the following 
+    $ python -m voc example.py
+
+You will see output like the following:
 
 .. code-block:: bash
 
-    $ Creating class 'example'...
-    $ Writing example/__init__.class...
-    $ Done.
+    Creating class 'example'...
+    Writing example/__init__.class...
+    Done.
 
-This will produce an ``__init__.class``, in the ``python/example`` namespace,
-that you can run on any Java 1.7+ VM. To run the classfile, you'll need the
-Python support libraries. These will eventually be available as a download;
-for now, you'll need to compile them. See the getting-started_ instructions 
-for details on how to compile it.
+This will produce an ``__init__.class`` in the ``python/example`` namespace.
+This classfile can run on any Java 1.7+ VM. To run the project, type:
 
-Once you've got the support Jarfile, you can run the example.class ensuring that
-the support jarfile is in your classpath. For example, using the Oracle Java VM,
-you would run::
+.. code-block:: bash
 
-    $ java -XX:-UseSplitVerifier -classpath dist/python-java.jar:. python.example.__init__
+    $ java -XX:-UseSplitVerifier -classpath ../voc/dist/python-java.jar:. python.example.__init__
     Hello, World
 
-.. note: Java 8
+.. note:: Java 8
 
    If you are using Java 8, substitute ``-noverify`` in place of ``-XX:-UseSplitVerifier``.
+
+Congratulations! You've just run your first Python program under Java using
+VOC! Now you're ready to get a little more adventurous.