Fleshed out a better structure for docs.

.gitignore

@@ -9,3 +9,4 @@ local.properties
 distribute-*
 tests/temp
 /org
+/docs/_build

docs/howto/index.rst

@@ -0,0 +1,9 @@
+How-to guides
+=============
+
+How-to guides are recipes that take the user through steps in key subjects. They are more advanced than tutorials and assume a lot more about what the user already knows than tutorials do, and unlike documents in the tutorial they can stand alone.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+

docs/index.rst

@@ -1,68 +1,26 @@
 VOC
 ===
 
-A transpiler that converts Python bytecode into Java bytecode.
+.. image:: https://travis-ci.org/pybee/voc.svg?branch=master
+    :target: https://travis-ci.org/pybee/voc
 
-This is experimental code. If it breaks, you get to keep all the shiny pieces.
+**VOC is an early alpha project. If it breaks, you get to keep all the shiny pieces.**
 
-What it does:
+VOC is a transpiler that takes Python 3.4 source code, and compile it into a Java
+class file that can then be executed on a JVM, or run through a DEX tool to
+run on Android. It does this *at the bytecode level*, rather than the source code level.
 
-* Provides an API to let you programmatically create Java class files.
-
-Quickstart
-----------
-
-Run away. :-)
-
-
-Why "VOC"?
-----------
-
-The `Vereenigde Oostindische Compagnie (VOC)`_, or Dutch East India Company,
-is often considered the be the world's first multinational corporation. It was
-also the first company to issue shares, and facilitate the trading of those
-shares. It was granted a 21 year monopoly to carry out trade activities in
-Asia, primarily the Spice Islands - the Dutch East Indies. They established a
-major trading port at Batavia - now Jakarta, on the island of Java (now part
-of Indonesia). As a result of their monopoly, the VOC became an incredibly
-valuable company, issuing an 18% annual dividend for almost 200 years.
-
-VOC was... the worlds first Enterprise site in Java. (rimshot!)
-
-.. _Vereenigde Oostindische Compagnie (VOC): https://en.wikipedia.org/wiki/Dutch_East_India_Company
-
-Community
----------
-
-VOC is part of the `BeeWare suite`_. You can talk to the community through:
-
- * `@pybeeware on Twitter`_
-
- * The `BeeWare Users Mailing list`_, for questions about how to use the BeeWare suite.
-
- * The `BeeWare Developers Mailing list`_, for discussing the development of new features in the BeeWare suite, and ideas for new tools for the suite.
-
-.. _BeeWare suite: http://pybee.org
-.. _Read The Docs: http://voc.readthedocs.org
-.. _@pybeeware on Twitter: https://twitter.com/pybeeware
-.. _BeeWare Users Mailing list: https://groups.google.com/forum/#!forum/beeware-users
-.. _BeeWare Developers Mailing list: https://groups.google.com/forum/#!forum/beeware-developers
-
-Contents:
+It honors Python 3.4 syntax and conventions, but also provides the ability to
+reference objects and classes defined in Java code, andimplement interfaces
+defined in Java code.
 
 .. toctree::
    :maxdepth: 2
    :glob:
 
-   internals/contributing
-   internals/roadmap
-   releases
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+   intro/index
+   tutorials/index
+   howto/index
+   topics/index
+   reference/index
+   internals/index

docs/internals/contributing.rst

@@ -35,16 +35,15 @@ Now you are ready to start hacking! Have fun!
 Java
 ----
 
-Java 7 is needed to run the tests because java 8 removed the option
-    
+Java 7 is needed to run the tests because Java 8 removed the option
+
     -XX:-UseSplitVerifier
 
-You can use java 8 if you have to. In that case go into the
-tests/utils.py and edit replace 
+You *can* use Java 8 if you have to. In that case go into the
+tests/utils.py and edit replace::
 
     -XX:-UseSplitVerifier
 
-with
+with::
 
     -noverify
-

docs/internals/index.rst

@@ -0,0 +1,10 @@
+Project Internals
+=================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   contributing
+   releases
+   roadmap

docs/internals/roadmap.rst

@@ -1,7 +1,13 @@
 VOC Roadmap
-===============
+===========
 
 VOC is a new project - we have lots of things that we'd like to do. If
 you'd like to contribute, providing a patch for one of these features:
 
-* Port to Python 3
+* Port a set of basic type operations
+
+* Implement a Python standard library module for
+
+* Implement StackMapFrames for the generated Java class files.
+
+* Work out how to run the CPython test suite with VOC

docs/intro/community.rst

@@ -0,0 +1,35 @@
+The VOC Developer and User community
+====================================
+
+VOC is part of the `BeeWare suite`_. You can talk to the community through:
+
+* `@pybeeware on Twitter`_
+
+* The `BeeWare Users Mailing list`_, for questions about how to use the BeeWare suite.
+
+* The `BeeWare Developers Mailing list`_, for discussing the development of new features in the BeeWare suite, and ideas for new tools for the suite.
+
+Code of Conduct
+---------------
+
+The BeeWare community has a strict `Code of Conduct`_. All users and developers are expected to adhere to this code.
+
+If you have any concerns about this code of conduct, or you wish to report a violation of this code, please contact the project founder `Russell Keith-Magee`.
+
+Contributing
+------------
+
+If you experience problems with VOC, `log them on GitHub`_. If you
+want to contribute code, please `fork the code`_ and `submit a pull request`_.
+
+.. _BeeWare suite: http://pybee.org
+.. _Read The Docs: http://voc.readthedocs.org
+.. _@pybeeware on Twitter: https://twitter.com/pybeeware
+.. _BeeWare Users Mailing list: https://groups.google.com/forum/#!forum/beeware-users
+.. _BeeWare Developers Mailing list: https://groups.google.com/forum/#!forum/beeware-developers
+.. _log them on Github: https://github.com/pybee/voc/issues
+.. _fork the code: https://github.com/pybee/voc
+.. _submit a pull request: https://github.com/pybee/voc/pulls
+
+.. _Code of Conduct: http://pybee.org/contributing/index.html
+.. _Russell Keith-Magee: mailto:[email protected]

docs/intro/faq.rst

@@ -0,0 +1,113 @@
+Frequently Asked Questions
+==========================
+
+Is VOC a source code converter?
+-------------------------------
+
+No. VOC operates *at the bytecode level*, rather than the source code level.
+It takes the CPython bytecode format (the `.pyc` files generated at runtime
+by CPython when the code is imported for the first time), and converts that
+bytecode directly into Java bytecode in a `.class` file. No intermediate Java
+source file is generated.
+
+Isn't this the same thing as Jython?
+------------------------------------
+
+No. Jython is an implementation of a Python interpreter in Java. This means
+it provides a REPL (an interactive prompt), and you *run* your Python code
+through Jython. VOC converts Python directly to a Java classfile; The VOC
+executable isn't needed at runtime (although there is a runtime support
+library that *is* needed).
+
+The `clamped` extension to Jython enable you to use Jython as a generator
+of class files - this is a closer analogy to what VOC does.
+
+The easiest way to demonstrate the difference between Jython and VOC is
+to look at the `eval()` and `exec()` methods. In Jython, these are key
+to how the process works, because they're just hooks into the runtime
+process of parsing and evaluating Python code. In VOC, these methods would
+be difficult to implement because VOC compiles all the class files up
+front. To implement `eval()` and `exec()`, you'd need to run VOC through
+VOC, and then expose an API that could be used at runtime to generate
+new `.class` files.
+
+How fast is VOC?
+----------------
+
+Faster than a slow thing; slower than a fast thing :-)
+
+Programming language performance is always nebulous to quantify. As a
+rough guide, it's about an order of magnitude slower than CPython on the
+same machine.
+
+This means it probably isn't fast enough for an application that is CPU
+bound. However, if this is the case, you can always write your CPU bound
+parts in *pure* Java, and call those directly from Python, same as you
+would for a CPython extension.
+
+It should also be noted that VOC is a very young project, and very little
+time has been spent on performance optimization. There are many obvious
+low hanging performance optimizations that could be explored as the project
+matures.
+
+What can I use VOC for?
+-----------------------
+
+You can use VOC anywhere that provides a Java runtime environment, but you
+want to write your logic in Python. For example:
+
+* Writing Android applicaitons
+
+* Writing Lucene/ElasticSearch custom functions
+
+* Writing Minecraft plugins
+
+* Writing web applications to deploy in a J2EE container
+
+In each of these cases, the project provides a Java (or Java-like, in the case
+of Android) environment. While some bridging might be possible with JNI, or by
+writing a thin Java shim that calls out to another language environment, these
+approaches mean you're developing a plugin at arms length.
+
+The VOC approach allows you to develop your Python application *as if it were
+native*. The class files even have references to the Python source code, so
+when a stack trace is generated, it will tell you the line of Python source
+that caused the problem.
+
+What version of Python does VOC require?
+----------------------------------------
+
+VOC runs under Python 3.4, and compiles Python 3.4 compatible bytecode.
+
+What version of Java does VOC require?
+--------------------------------------
+
+VOC runs on:
+
+* Java 6 without any special handling;
+* Java 7 by enabling the `-XX:-UseSplitVerifier` flag at runtime;
+* Java 8 by enabling the `-noverify` flag at runtime.
+
+The complication with Java 7 and Java 8 is due to a feature of class files
+(called a Stack Map Frame) that was introduced as an optional feature in
+Java 6, and has been decreasingly optional in each subsequent release.
+
+It would be entirely possible to generate Stack Map Frames for the generated
+class files from the information in a Python class file, but the developers
+haven't had a chance to get around to that yet.
+
+Why "VOC"?
+----------
+
+The `Vereenigde Oostindische Compagnie (VOC)`_, or Dutch East India Company,
+is often considered the be the world's first multinational corporation. It was
+also the first company to issue shares, and facilitate the trading of those
+shares. It was granted a 21 year monopoly to carry out trade activities in
+Asia, primarily the Spice Islands - the Dutch East Indies. They established a
+major trading port at Batavia - now Jakarta, on the island of Java (now part
+of Indonesia). As a result of their monopoly, the VOC became an incredibly
+valuable company, issuing an 18% annual dividend for almost 200 years.
+
+VOC was... the worlds first Enterprise site in Java. (rimshot!)
+
+.. _Vereenigde Oostindische Compagnie (VOC): https://en.wikipedia.org/wiki/Dutch_East_India_Company

docs/intro/getting-started.rst

@@ -0,0 +1,4 @@
+Getting Started
+===============
+
+Using Python 3.4, install `voc`...

docs/intro/index.rst

@@ -0,0 +1,17 @@
+About VOC
+=========
+
+VOC is a transpiler that takes Python 3.4 source code, and compiles it into a
+Java class file that can then be executed on a JVM.
+
+It honors Python 3.4 syntax and conventions, but also provides the ability to
+reference objects and classes defined in Java code, andimplement interfaces
+defined in Java code.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   community
+   faq
+   getting-started

docs/reference/index.rst

@@ -0,0 +1,4 @@
+Reference
+=========
+
+This is the technical reference for public APIs provided by VOC.

docs/topics/index.rst

@@ -0,0 +1,5 @@
+Topic guides
+============
+
+Aimed at explaining (at a fairly high level) rather than doing.
+

docs/tutorials/index.rst

@@ -0,0 +1,11 @@
+Tutorials
+=========
+
+These tutorials are step-by step guides for using VOC. They all assume that
+you've set up your development environment as described in :doc:`/intro/getting-started`.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   tutorial-0

docs/tutorials/tutorial-0.rst

@@ -0,0 +1,44 @@
+Tutorial 0 - Hello, world!
+==========================
+
+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
+: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
+
+Start a new project
+-------------------
+
+TODO - write an actual tutorial :-)
+
+
+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
+
+.. note: Java 8
+
+   If you are using Java 8, substitute ``-noverify`` in place of ``-XX:-UseSplitVerifier``.