fleshing out build system docs

ParadropLabs · Jun 22, 2015 · 8f031db · 8f031db
1 parent 2dcde53
commit 8f031db
Show file tree

Hide file tree

Showing 14 changed files with 181 additions and 69 deletions.
diff --git a/docs/api/modules.rst b/docs/api/modules.rst
@@ -0,0 +1,30 @@
+Internal Documentation
+======================
+
+Subpackages
+-----------
+
+.. toctree::
+
+    paradrop.backend
+    paradrop.frontend
+
+Submodules
+----------
+
+paradrop.paradrop module
+------------------------
+
+.. automodule:: paradrop.paradrop
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: paradrop
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/paradrop.backend.rst b/docs/api/paradrop.backend.rst
@@ -0,0 +1,22 @@
+paradrop.backend package
+========================
+
+Submodules
+----------
+
+paradrop.backend.connection module
+----------------------------------
+
+.. automodule:: paradrop.backend.connection
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: paradrop.backend
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/paradrop.frontend.rst → docs/api/paradrop.frontend.rst b/docs/paradrop.frontend.rst → docs/api/paradrop.frontend.rst
@@ -9,10 +9,14 @@ paradrop.frontend.stuff module
 
 .. automodule:: paradrop.frontend.stuff
     :members:
+    :undoc-members:
+    :show-inheritance:
 
 
 Module contents
 ---------------
 
 .. automodule:: paradrop.frontend
-    :members:
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/paradrop.rst → docs/api/paradrop.rst b/docs/paradrop.rst → docs/api/paradrop.rst
@@ -6,6 +6,7 @@ Subpackages
 
 .. toctree::
 
+    paradrop.backend
     paradrop.frontend
 
 Submodules
@@ -16,3 +17,14 @@ paradrop.paradrop module
 
 .. automodule:: paradrop.paradrop
     :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: paradrop
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/build system.rst b/docs/build system.rst
@@ -1,26 +1,56 @@
 Build System
 ====================================
 
-ORPHANED DOCS
+Paradrop includes a set of build tools to make development as easy as possible. 
+
+Currently this system takes the form of a bash script that automates installation and execution, but 
+in time this may evolve into a published python package. This page outlines the steps required to 
+manually build the components required to develop with paradrop.
+
+Components in the build process:
+
+- `Installing and running Ubuntu Snappy`_
+- `Building paradrop`_
+- `Installing paradrop`_
+- `Creating chutes`_
+
+Installing and running Ubuntu Snappy
+------------------------------------
 
-### Snappy
 [Snappy](https://developer.ubuntu.com/en/snappy/) is an Ubuntu release focusing on low-overhead for a large set of platforms. These instructions are for getting a Snappy instance up and running using 'kvm'. 
 
-Download and unzip a snappy image 
-```
-wget http://releases.ubuntu.com/15.04/ubuntu-15.04-snappy-amd64-generic.img.xz
-unxz ubuntu-15.04-snappy-amd64-generic.img.xz
-```
+Download and unzip a snappy image::
+
+    wget http://releases.ubuntu.com/15.04/ubuntu-15.04-snappy-amd64-generic.img.xz
+    unxz ubuntu-15.04-snappy-amd64-generic.img.xz
+
+
+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
+
+
+Building paradrop
+--------------------
+
+Snappy is a closed system (by design!). Arbitrary program installation is not allowed, so to allow paradrop access to the wide world of ``pypi`` the build system relies on two tools. 
+
+- ``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.
+
+
+
+Installing paradrop
+--------------------
+
+
+Creating chutes
+--------------------
 
-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
-```
 
 
 ### Virtualenv

diff --git a/docs/conf.py b/docs/conf.py
@@ -25,6 +25,8 @@
 
 # -- General configuration ------------------------------------------------
 
+add_module_names = False
+
 import os
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
@@ -220,25 +222,25 @@
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+    # The paper size ('letterpaper' or 'a4paper').
+    #'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+    # The font size ('10pt', '11pt' or '12pt').
+    #'pointsize': '10pt',
 
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+    # Additional stuff for the LaTeX preamble.
+    #'preamble': '',
 
-# Latex figure (float) alignment
-#'figure_align': 'htbp',
+    # Latex figure (float) alignment
+    #'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'paradrop.tex', u'paradrop Documentation',
-   u'Paradrop Labs', 'manual'),
+    (master_doc, 'paradrop.tex', u'paradrop Documentation',
+     u'Paradrop Labs', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -281,9 +283,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, 'paradrop', u'paradrop Documentation',
-   author, 'paradrop', 'One line description of project.',
-   'Miscellaneous'),
+    (master_doc, 'paradrop', u'paradrop Documentation',
+     author, 'paradrop', 'One line description of project.',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.

diff --git a/docs/index.rst b/docs/index.rst
@@ -6,22 +6,19 @@
 Paradrop
 ====================================
 
-Contents:
+TL;DR
+-----
+
+Get started coding right away with the :doc:`quickstart`.
+
+
 
 .. toctree::
    :maxdepth: 2
+   :hidden:
 
-   overview
    installation
    developing for paradrop
-   modules
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   api/modules
 
+.. include:: overview.rst
diff --git a/docs/modules.rst b/docs/modules.rst
diff --git a/paradrop/paradrop/__init__.py b/paradrop/paradrop/__init__.py
@@ -1 +1,2 @@
-from .paradrop import main
+
+from .paradrop import main
diff --git a/paradrop/paradrop/backend/__init__.py b/paradrop/paradrop/backend/__init__.py
@@ -0,0 +1,3 @@
+'''
+Testing package documetation
+'''
diff --git a/paradrop/paradrop/backend/connection.py b/paradrop/paradrop/backend/connection.py
@@ -0,0 +1,7 @@
+
+class BackendConnection:
+    def __init__(self):
+        '''
+        More docs testing
+        '''
+        pass
diff --git a/paradrop/paradrop/frontend/__init__.py b/paradrop/paradrop/frontend/__init__.py
@@ -1 +1 @@
-# import stuff
+# import stuff
diff --git a/paradrop/paradrop/frontend/stuff.py b/paradrop/paradrop/frontend/stuff.py
@@ -2,14 +2,15 @@
 Sample documentation
 '''
 
+
 def afunction():
     """This function does something... from inside frontend.
 
-    :param name: The name to use. 
-    :type name: str. 
-    :param state: Current state to be in. 
-    :type state: bool. 
-    :returns: int -- the return code. 
+    :param name: The name to use.
+    :type name: str.
+    :param state: Current state to be in.
+    :type state: bool.
+    :returns: int -- the return code.
     :raises: AttributeError, KeyError
-    """ 
-    print 'Just testing, thanks.'
+    """
+    print 'Just testing, thanks.'
diff --git a/paradrop/paradrop/paradrop.py b/paradrop/paradrop/paradrop.py
@@ -1,29 +1,39 @@
-from flask import Flask
+'''
+Core module. Contains the entry point into Paradrop and establishes all other modules.
+Does not implement any behavior itself.
+'''
 
+from flask import Flask
 import frontend
 
+
 def main():
-    """This function does something.
+    """
+    This function does something. Right now what its doing is demonstrating
+    a docstring with sphinxy additions.
 
-    :param name: The name to use. 
-    :type name: str. 
-    :param state: Current state to be in. 
-    :type state: bool. 
-    :returns: int -- the return code. 
+    :param name: The name to use.
+    :type name: str.
+    :param state: Current state to be in.
+    :type state: bool.
+    :returns: int -- the return code.
     :raises: AttributeError, KeyError
-    """ 
+    """
     app = Flask(__name__)
 
     @app.route('/')
     def hello_world():
         return 'hello world!'
 
-    #assign to eth0 dynamically (or run it on 80)
+    # assign to eth0 dynamically (or run it on 80)
     # app.run('10.0.2.15', port = 7777)
 
-    #running locally
-    #TODO: determine if running locally or on snappy 
-    app.run(port = 7777)
+    # running locally
+    # TODO: determine if running locally or on snappy
+    app.run(port=7777)
+
+    # Just playing with anaconda autocomplete
+    frontend.stuff.afunction()
 
 if __name__ == "__main__":
     main()