fixing up documentation.

docs/cookbook/bestpractices.rst

@@ -33,4 +33,5 @@ will cache the script, thus allowing offline execution.
 
 
 .. code-block:: python
+
     build.include("http://my-remote-base", cache=True)

docs/cookbook/reuse.rst

@@ -10,7 +10,7 @@ works for you.
 build.includes
 --------------
 
-Uranium provides an icludes function to download and execute a remote
+Uranium provides an includes function to download and execute a remote
 script. For example, let's say you want to share a common test
 function, as well as ensure builds are using a private repository. You
 can host a file uranium_base.py that looks like:
@@ -76,6 +76,7 @@ all the tasks, and download it in your ubuild.py.
 
 
 .. code-block:: python
+
     # in a module mycompany_build
     import subprocess
     import uranium
@@ -104,6 +105,7 @@ all the tasks, and download it in your ubuild.py.
 And your consumer script will look like:
 
 .. code-block:: python
+
     # ubuild.py in the project.
     from uranium import get_remote_script
 

docs/dependency.rst

@@ -0,0 +1,27 @@
+===========================
+Declaring Task Dependencies
+===========================
+
+Uranium provides a declarative task dependency system
+through task_requires::
+
+    from uranium import task_requires
+
+    def main(build):
+        print("main was")
+
+    # this ensures main is run first, during
+    # an execution.
+    @task_requires("main")
+    def test(build):
+        print("test was run")
+
+    # a list can be passed in. In that case,
+    # each dependency is executed in the order
+    # it appears in the list.
+    #
+    # notice that a string with the task name,
+    # or the task itself can be passed in.
+    @task_requires(["main", test])
+    def build_docs(build):
+        print("main was")

docs/index.rst

@@ -53,6 +53,7 @@ Contents:
    examples
    cookbook/cookbook
    config
+   dependency
    envs
    executables
    history

docs/installation.rst

@@ -25,6 +25,13 @@ You would then enter a directory with a ubuild.py, and execute the uranium entry
 
     uranium
 
+.. note::
+
+   This approach is not ideal, as it enforces strict version restrictions
+   of Uranium's dependencies onto your globally installed packages.
+
+   for most situations, it's suggested to use the uranium script.
+
 
 ----------------------
 Use the Uranium Script
@@ -57,8 +64,7 @@ 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.
+own bootstrapping script. This is recommended when setting up a
+structure for an organization, as a common standalone script ensures
+that changes can be applied globally with ease, in contrast to
+updating each uranium script in every location individually.

docs/rules.rst

@@ -4,7 +4,9 @@ Rules
 
 **Warning: This is an experimental api. It is not a final design, and could be modified in the future.**
 
-Rules are a way to help prevent re-executing tasks unnecessarily. For example, not re-downloading a script if it has already been downloaded:
+Rules are a way to help prevent re-executing tasks unnecessarily. For
+example, not re-downloading a script if it has already been
+downloaded:
 
 .. code-block:: python
 

docs/tutorial.rst

@@ -4,19 +4,21 @@ Tutorial
 
 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.
+Let's start with a simple example: setting up a virtualenv and install
+an egg.
 
-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.
+unix-based commands are used for the tutorial, but this documentation
+attempts to describe these steps so they can be easily replicated on
+other operating systems.
 
 For the purpose of the tutorial, let's create a root directory:
 
 .. code-block:: bash
 
   $ mkdir -p /tmp/uranium-tut/ && cd /tmp/uranium-tut/
 
-Start by downloading uranium. uranium is a python wrapper around the uranium library that handles the following:
+Start by downloading the uranium script. The uranium script 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
@@ -37,7 +39,7 @@ Now you need a ubuild.py file. Let's make one now:
 
   $ touch ubuild.py
 
-And we'll need to fill it in with at the very least, a main method:
+And we'll need to fill it in with at the very least, a main function:
 
 .. code-block:: python
 
@@ -47,7 +49,7 @@ And we'll need to fill it in with at the very least, a main method:
 
 Now, you can run uranium. Try it now:
 
-.. code-block:: python
+.. code-block:: bash
 
     $ ./uranium
     installing virtualenv...
@@ -61,25 +63,27 @@ Now, you can run uranium. Try it now:
     [HH:MM:SS] URANIUM FINISHED
     [HH:MM:SS] ================
 
-And congrats, you've had your first Uranium run! Of course, all this
-did was set up a virtualenv. Now let's start working on real functionality.
+
+And congrats, you've had your first Uranium run! Uranium read the
+ubuild.py, found the main function, and executed it. However, the only
+result is having a set up virtualenv. The next step is working or real
+functionality.
 
 ------------------------------
 Developing and Installing Eggs
 ------------------------------
 
 We started with an empty main method. To add eggs and develop-eggs,
-you can use the packages object attached to the build:
+you can use the packages attribute of build:
 
 .. code-block:: python
 
     def main(build):
-        build.packages.install("nose", version="==1.3.4")
+    build.packages.install("nose", version="==1.3.4")
 
 And let's run uranium again:
 
-
-.. code-block:: python
+.. code-block:: bash
 
     $ ./uranium
     setting up uranium...

makefile

@@ -1,11 +1,11 @@
 test:
-	./uranium/scripts/uranium_standalone --uranium-dir=. test_no_deps ${ARGS}
-
-test_full:
 	./uranium/scripts/uranium_standalone --uranium-dir=. test ${ARGS} -v
 
 build:
 	./uranium/scripts/uranium_standalone --uranium-dir=.
 
 distribute:
 	./uranium/scripts/uranium_standalone --uranium-dir=. distribute
+
+docs:
+	./uranium/scripts/uranium_standalone --uranium-dir=. build_docs

ubuild.py

@@ -2,51 +2,39 @@
 from uranium import task_requires
 
 
-def _install_test_modules(build):
-    build.packages.versions.update({
-        "httpretty": "==0.8.10",
-    })
-
-    build.packages.install("pytest", version="==2.9.2")
-    build.packages.install("pytest-cov")
-    build.packages.install("httpretty")
-
-
-def distribute(build):
-    """ distribute the uranium package """
-    build.packages.install("wheel")
-    build.executables.run([
-        "python", "setup.py",
-        "bdist_wheel", "--universal", "upload"
-    ])
-
-
 def main(build):
-    _install_test_modules(build)
     build.packages.install(".", develop=True)
 
 
 @task_requires("main")
 def test(build):
-    _install_test_modules(build)
-    test_no_deps(build)
-
-
-def test_no_deps(build):
     """ execute tests """
+    build.packages.install("pytest", version="==2.9.2")
+    build.packages.install("pytest-cov")
+    build.packages.install("httpretty", version="==0.8.10")
     build.executables.run([
         "py.test", os.path.join(build.root, "tests"),
         "--cov", "uranium",
         "--cov-config", "coverage.cfg",
     ] + build.options.args)
 
 
+@task_requires("main")
 def build_docs(build):
     """ build documentation """
-    main(build)
     build.packages.install("Babel")
     build.packages.install("Sphinx")
+    build.packages.install("sphinx_rtd_theme")
     return build.executables.run([
         "sphinx-build", "docs",
         os.path.join("docs", "_build")
     ] + build.options.args)[0]
+
+
+def distribute(build):
+    """ distribute the uranium package """
+    build.packages.install("wheel")
+    build.executables.run([
+        "python", "setup.py",
+        "bdist_wheel", "--universal", "upload"
+    ])