updated docs, fixed small bug in buildtools

docs/api/modules.rst

@@ -8,14 +8,15 @@ Subpackages
 
     paradrop.backend
     paradrop.frontend
+    paradrop.lib
 
 Submodules
 ----------
 
-paradrop.paradrop module
-------------------------
+paradrop.main module
+--------------------
 
-.. automodule:: paradrop.paradrop
+.. automodule:: paradrop.main
     :members:
     :undoc-members:
     :show-inheritance:

docs/api/paradrop.backend.pdfcd.rst

@@ -0,0 +1,38 @@
+paradrop.backend.pdfcd package
+==============================
+
+Submodules
+----------
+
+paradrop.backend.pdfcd.apichute module
+--------------------------------------
+
+.. automodule:: paradrop.backend.pdfcd.apichute
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+paradrop.backend.pdfcd.apiutils module
+--------------------------------------
+
+.. automodule:: paradrop.backend.pdfcd.apiutils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+paradrop.backend.pdfcd.server module
+------------------------------------
+
+.. automodule:: paradrop.backend.pdfcd.server
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: paradrop.backend.pdfcd
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/paradrop.backend.rst

@@ -1,6 +1,13 @@
 paradrop.backend package
 ========================
 
+Subpackages
+-----------
+
+.. toctree::
+
+    paradrop.backend.pdfcd
+
 Submodules
 ----------
 
@@ -12,6 +19,14 @@ paradrop.backend.connection module
     :undoc-members:
     :show-inheritance:
 
+paradrop.backend.main module
+----------------------------
+
+.. automodule:: paradrop.backend.main
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 
 Module contents
 ---------------

docs/api/paradrop.lib.api.rst

@@ -0,0 +1,30 @@
+paradrop.lib.api package
+========================
+
+Submodules
+----------
+
+paradrop.lib.api.pdapi module
+-----------------------------
+
+.. automodule:: paradrop.lib.api.pdapi
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+paradrop.lib.api.pdrest module
+------------------------------
+
+.. automodule:: paradrop.lib.api.pdrest
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: paradrop.lib.api
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/api/paradrop.rst → docs/api/paradrop.lib.rst

@@ -1,21 +1,21 @@
-paradrop package
-================
+paradrop.lib package
+====================
 
 Subpackages
 -----------
 
 .. toctree::
 
-    paradrop.backend
-    paradrop.frontend
+    paradrop.lib.api
+    paradrop.lib.utils
 
 Submodules
 ----------
 
-paradrop.paradrop module
-------------------------
+paradrop.lib.settings module
+----------------------------
 
-.. automodule:: paradrop.paradrop
+.. automodule:: paradrop.lib.settings
     :members:
     :undoc-members:
     :show-inheritance:
@@ -24,7 +24,7 @@ paradrop.paradrop module
 Module contents
 ---------------
 
-.. automodule:: paradrop
+.. automodule:: paradrop.lib
     :members:
     :undoc-members:
     :show-inheritance:

docs/api/paradrop.lib.utils.rst

@@ -0,0 +1,30 @@
+paradrop.lib.utils package
+==========================
+
+Submodules
+----------
+
+paradrop.lib.utils.output module
+--------------------------------
+
+.. automodule:: paradrop.lib.utils.output
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+paradrop.lib.utils.pdutils module
+---------------------------------
+
+.. automodule:: paradrop.lib.utils.pdutils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: paradrop.lib.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/build system.rst

@@ -26,10 +26,12 @@ Download and unzip a snappy image::
 
 
 Launch the snappy image using kvm::
+
     kvm -m 512 -redir :8090::80 -redir :8022::22 ubuntu-15.04-snappy-amd64-generic.img
 
 
 Connect to local instance using ssh::
+
     ssh -p 8022 ubuntu@localhost
 
 
@@ -41,56 +43,43 @@ Snappy is a closed system (by design!). Arbitrary program installation is not al
 - ``virtualenv`` is a tool that creates encapsulated environments in which python packages can be installed. 
 - ``pex`` can compress python packages into a zip file that can be executed by any python interpreter.
 
+Dependancies for paradrop are packaged with the final snap as a pex file created by freezing a virtualenv. These are the steps needed to do this:
 
+1. ``venv.pex`` is packaged with paradrop source code. This is a pex that contains only the virtualenv package. This file bootstraps virtualenv so it does not need to be installed on the local system. 
+2. A new virtual environment is created under ``/buildenv/env`` by calling ``venv.pex ./buildenv/env``
+3. The environment is activated with ``source ./buildenv/env/bin/activate``. Any python package installations will now be placed here. 
+4. Paradrop is installed with ``pip install -e .``. This installs paradrop in the virtual as well as all dependancies. Dependancies are listed in ``src/setup.py``. You must add depedencies here in order to include new python packages with paradrop. 
+5. Dependancies are saved into ``bin/pddepedencies.pex`` with the command ``pex -r docs/requirements.txt -o bin/pddepedencies.pex``. Note: requirements are written out to the file in step 4. This is done so that the ``paradrop`` dependancy is not included in the pex, since pex won't know how to look for it! The command used to do this is ``pip freeze | grep -v 'pex' | grep -v 'paradrop' > docs/requirements.txt``.
 
-Installing paradrop
---------------------
+At this point you can run paradrop by activating the virtualenv (step #3) and then simply calling ``paradrop``. Note that the bundled dependancies pex does not affect locally running paradrop instances-- its used in the next section.
 
 
-Creating chutes
+Installing paradrop
 --------------------
+All programs installed on snappy are called ``snaps``. Snappy development tools are required to build snaps::
 
+    sudo add-apt-repository ppa:snappy-dev/tools
+    sudo apt-get update
+    sudo apt-get install snappy-tools bzr
 
+To build a snap::
 
+    snappy build .
 
-### Virtualenv
-(Note: not using virtualenv for pex configuration later, but it makes things easier.)
-virtualenv is a tool that allows developers to manage environments, dependancies and more for python programs. In this case its used both as a management tool and a packageing tool (along with pex.)
+Push a snap to a running instance of snappy::
 
-We may choose to go with this as part of the build process since it doesn't require building the python package, but perhaps not. 
+    snappy-remote --url=ssh://localhost:8022 install SNAPNAME
 
-To load the current virtualenv, use 
-    source [envdir]/bin/activate
 
-To deactivate, use
-    deactivate
+Creating chutes
+--------------------
+
+In progress.
 
-To install something like twisted be sure to have python developer tools already installed:
-    sudo apt-get install python-dev
 
 ## Contributing
 All contributions must follow [PEP8](https://www.python.org/dev/peps/pep-0008/) and have relevant tests. Please document as needed. 
 
-## Miscellanious Help
-
-
-### Paradrop
-Paradrop is packaged as a python package. This means you can install it on a local system without needing to interact with snappy. Be warned-- the package on its own assumes that docker and Open vSwitch are installed, and may fail if these components are not already installed!
-
-
-
-
-Build a Snap and push it to a running snappy instance. Make sure you're in the directory you're trying to build before attempting these steps. This example loads one the sample snappy apps. 
-```
-snappy build .
-snappy-remote --url=ssh://localhost:8022 install ./hello-world_1.0.17_all.snap
-```
-
-Snaps with binaries must have those binaries explicitly called. Those with services are automatically started. This example again uses the sample 'hello-world' shipped with the snappy examples repository.
-```
-hello-world.echo
-```
-
 Compiling documentation
 ```
 pip install sphinx sphinx-autobuild sphinx-rtd-build

docs/chutes.rst

@@ -0,0 +1,6 @@
+Making paradrop chutes
+====================================
+
+Wondering how to make applications that run on paradrop? Well wonder no more!
+
+Actually, you may have to wonder for a little longer, since there's not content to sate your curiousity yet. Sorry!

docs/development.rst

@@ -0,0 +1,14 @@
+Developing for paradrop
+====================================
+
+Ready to get started with paradrop? This section can help you understand how paradrop is built and how to use the provided tools to get up and running right away. 
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart
+   build system
+   doctests
+

docs/doctests.rst

@@ -0,0 +1,31 @@
+Documentation and tests
+====================================
+
+Documentation is handled by `sphinx <http://sphinx-doc.org/>`_ and readthedocs.
+
+Testing is a joint effort between `nosetests <https://nose.readthedocs.org/en/latest/>`_, travis-ci, and coveralls. 
+
+
+Documentation
+--------------
+Information about docs creation, management, and display. 
+
+Sphinx reads files in `reStructuredText <http://sphinx-doc.org/rest.html>`_ and builds a set of HTML pages. Every time a new commit is pushed to github, readthedocs automatically updates documentation. 
+
+Additionally, sphinx knows all about python! The directives ``automodule``, ``autoclass``, ``autofunction`` and more instruct sphinx to inspect the code located in ``src/`` and build documentation from the docstrings within.
+
+For example, the directive ``.. automodule:: paradrop.backend`` will build all the documentation for the given package. See google for more instructions. 
+
+All docstring documentation is rebuilt on every commit (unless there's a bug in the code.) Sphinx does not, however, know about structural changes in code! To alert sphinx of these changes, use the ``autodoc`` feature::
+
+    sphinx-apidoc -f -o docs/api src/paradrop/
+
+This scans packages in the ``src/paradrop`` directory and creates .rst files in ``docs/api``. The root file ``index.rst`` links to ``modules.rst``, connecting the newly generated api code with the main documentation.
+
+To create the documentation locally, run::
+
+    cd docs
+    make html
+    python -m SimpleHTTPServer 9999
+
+Open your web browser of choice and point it to http://localhost:9999/_build/html/index.html.

docs/index.rst

@@ -9,16 +9,14 @@ Paradrop
 TL;DR
 -----
 
-Get started coding right away with the :doc:`quickstart`.
-
-
+Get started coding right away with the :doc:`quickstart`. 
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
-   installation
-   developing for paradrop
+   chutes
+   development
    api/modules
 
 .. include:: overview.rst