revamping documentation.

docs/config.rst

@@ -12,13 +12,13 @@ Configuration variables are useful in a variety of situations, including:
 
 .. code:: python
 
-    # config.defaults can be used to set some defaults.
+    # config.set_defaults can be used to set some default values.
     build.config.set_defaults({
         "development": "false"
     })
 
     def test(build):
-        # one can set development mode by adding a -c development=true before the directive:
+        # one can set development mode by adding a -c development=true before the task:
         # ./uranium -c development=true test
         if build.config["development"].startswith("t"):
             build.packages.install(".", develop=True)

docs/executables.rst

@@ -2,6 +2,14 @@
 Executables
 ===========
 
+EXPERIMENTAL
+============
+
+This function is still being reviewed, and may be subject to changes
+to it's signature and naming before uranium 1.0.
+
+
+
 Uranium provides a convenience wrapper to interact with
 executables. This can handle some common scenarios, like execute a
 script and patch in the stdin, stdout, and stderr streams of the main

docs/index.rst

@@ -10,34 +10,38 @@ Uranium: a Python Build System
 What is Uranium?
 ----------------
 
-Uranium is a build utility for Python. It's designed to help assist
-with the build process for Python services that require more than a
-virtualenv + "pip install -r requirements.txt". The built in features
-include:
+Uranium is an assembly framework for Python, designed to help
+assist with the assembling Python services. Uranium provides
+tools for dependency management, reuse of assembly scripts, configuration, and
+other common requirements for an assembly system.
 
-* isolation via virtualenv
-* package installation via programatically driven pip
+Uranium provides package isolation and management via virtualenv and
+pip, and is a good solution to problems that arise in large-scale
+assembly systems:
 
-Some of the reasons you may want to use Uranium include:
-
-* installing native dependencies
-* executing arbitrary scripts
+* setting a version pin across multiple projects.
+* reusing common assembly tasks, such as downloading configuration, or
+  compiling native dependencies.
+* providing a simple configuration system that can be consumed by
+  multiple projects.
 
 An example configuration looks like this:
 
 .. code:: python
 
+    import subprocess
     # this is a uranium.py file
     # it requires at the minimum a function
     # main that accepts a parameter build.
     def main(build):
         # you can change the index urls as desired.
         build.packages.index_urls = ["http://www.mycompany.com/index",
                                      "http://pypi.python.org"]
-        # eggs are installed this way.
+        # packages are installed using the packages.install method.
         build.packages.install("py.test")
-        # you can execute arbitrary scripts that are installed within a sandbox.
-        build.executables.run(["py.test", "mytests"])
+        # once an egg is installed, you can run arbitrary scripts installed
+        # into the sandbox:
+        return subprocess.call(["py.test", "mytests"] + build.options.args)
 
 Contents:
 

docs/installation.rst

@@ -2,7 +2,7 @@
 Installation
 ============
 
-There are two ways you can invoke uranium:
+There are two ways one can run uranium:
 
 * install it globally
 * use the uranium script
@@ -12,14 +12,14 @@ There are two ways you can invoke uranium:
 Installing it globally
 ----------------------
 
-You can install Uranium globally with any Python package manager:
+You can install uranium globally with any Python package manager:
 
 .. code::
 
     pip install uranium
 
 
-You would then enter a directory with a uranium.py, and execute the uranium entry point:
+You would then enter a directory with a ubuild.py, and execute the uranium entry point:
 
 .. code::
 
@@ -41,10 +41,24 @@ You would then execute the local uranium script instead:
 
   ./uranium
 
-It's recommended to use the uranium script rather than the standalone,
-which will ensure that your project will pick up future updates to
-Uranium and the setup script.
 
-The uranium script also provides a blueprint on how to provide your own bootstrapping script. This is recommended when
-setting a pattern for an organization, as a common standalone script ensures that any changes the version of Uranium used,
-or custom configuration can be applied globally, in contrast to updating each uranium script individually.
+--------------------------
+Which method should I use?
+--------------------------
+
+Utilizing the uranium_standalone or uranium script is recommended. The
+standalone scripts allow consumers to assemble your code without the
+need for any modification of their machine globally. It also allows
+for each individual project to choose their version of uranium, if that becomes
+necessary.
+
+The uranium script requires trust in the uranium project and the
+developers, as it is downloads the standalone script from the git
+repository and executes that script.
+
+The uranium script also provides a blueprint on how to provide your
+own bootstrapping script. This is recommended when setting a pattern
+for an organization, as a common standalone script ensures that any
+changes the version of Uranium used, or custom configuration can be
+applied globally, in contrast to updating each uranium script
+individually.

docs/options.rst

@@ -3,7 +3,7 @@ Options
 =======
 
 With uranium, arguments that configure uranium itself should be passed
-in before the directive, and any argument passed in afterward
+in before the task name, and any argument passed in afterward
 should be specific for the function.
 
 For example, consider the following scenario:

docs/packages.rst

@@ -2,16 +2,16 @@
 Managing Packages
 =================
 
-Any configuration related to packages is done through the Packages object. Here is an example showing some of the more
-common operations:
+Any configuration related to packages is done through the Packages
+object. Here is an example showing some common operations:
 
 .. code:: python
 
           def main(build):
               # it's possible to set the index urls that packages will be installed from:
               build.packages.index_urls = ["http://www.mycompany.com/python_index"]
 
-              # this directive installs the package "py.test" with version 2.7.0. It's
+              # this method installs the package "py.test" with version 2.7.0. It's
               # available in the sandbox as soon as the package is installed.
               build.packages.install("py.test", version="==2.7.0")
 

docs/tasks.rst

@@ -0,0 +1,25 @@
+=====
+Task
+=====
+
+
+
+environment variables can be modified as a regular dictionary:
+
+
+.. code:: python
+
+    import os
+
+    def main(build):
+        build.environment["EDITOR"] = "emacs"
+        build.environment["LD_LIBRARY_PATH"] = os.path.join(build.root, "lib")
+
+
+------------------
+Full API Reference
+------------------
+
+
+.. autoclass:: uranium.environment_variables.EnvironmentVariables
+    :members: __setitem__, __getitem__

docs/tutorial.rst

@@ -6,7 +6,7 @@ This tutorial is an introduction to the basic concepts around Uranium.
 
 Let's start with a simple example: setting up a virtualenv and install an egg.
 
-We'll use unix-based commands for the tutorial, but we will attempt to
+We will use unix-based commands for the tutorial, but attempt to
 describe the steps so these steps can be replicated on other operating
 systems.
 
@@ -16,7 +16,7 @@ For the purpose of the tutorial, let's create a root directory:
 
   $ mkdir -p /tmp/uranium-tut/ && cd /tmp/uranium-tut/
 
-We first start by downloading uranium. uranium is a python wrapper around the uranium library that handles the following:
+Start by downloading uranium. uranium is a python wrapper around the uranium library that handles the following:
 
 * downloading and setting up a virtualenv
 * installing the uranium script into the virtualenv
@@ -42,7 +42,7 @@ And we'll need to fill it in with at the very least, a main method:
 .. code-block:: python
 
     def main(build):
-        print("Uranium works!")
+        print("uranium works!")
 
 
 Now, you can run uranium. Try it now:
@@ -56,6 +56,7 @@ Now, you can run uranium. Try it now:
     [HH:MM:SS] ================
     [HH:MM:SS] STARTING URANIUM
     [HH:MM:SS] ================
+    [HH:MM:SS] uranium works!
     [HH:MM:SS] ================
     [HH:MM:SS] URANIUM FINISHED
     [HH:MM:SS] ================
@@ -100,12 +101,12 @@ If you want to install an egg for development purposes, you can use:
     def main(build):
         build.packages.install(".", develop=True)
 
-------------------------------
-Executing Different Directives
-------------------------------
+-------------------------
+Executing Different Tasks
+-------------------------
 
 the ubuild.py can define other methods, and they can be executed as well. Any
-method that accepts a single parameter build can be a directive that's executed:
+method that accepts a single parameter build can be a task that's executed:
 
 
 

uranium/build.py

@@ -15,6 +15,7 @@
 from .lib.sandbox import Sandbox
 from .lib.log_templates import STARTING_URANIUM, ENDING_URANIUM
 from .lib.utils import log_multiline
+from .remote import get_remote_script
 
 u_assert = get_assert_function(UraniumException)
 
@@ -85,7 +86,24 @@ def run_task(self, task_name):
         return self._tasks[task_name](self)
 
     def task(self, f):
+        """
+        a decorator that adds the given function as a task.
+
+        e.g.
+
+        @build.task
+        def main(build):
+            build.packages.install("httpretty")
+
+        this is useful in the case where tasks are being sourced from
+        a different file, besides ubuild.py
+        """
         self._tasks.add(f)
+        return f
+
+    def include(self, script_path):
+        """ executes the script at the specified path. """
+        get_remote_script(script_path, build=self)
 
     def run(self, options):
         if not self._sandbox: