Update documentation: Add Parameter passing

Restructure documentation to better suite the parameter passing
section(s); add two sections: how to invoke xnt to pass parameters,
and how to add/use them in the build file

3 files changed, 108 insertions, 63 deletions

diff --git a/docs/source/buildfile.rst b/docs/source/buildfile.rst
index 3867830..4372874 100644
--- a/docs/source/buildfile.rst
+++ b/docs/source/buildfile.rst
@@ -69,73 +69,28 @@ purpose of the target, or what the target accomplishes when ran. Finally, we
 call ``mkdir`` of the ``xnt.tasks`` module. This function, if not obvious by
 the name, creates a directory named 'build' (see :doc:`taskreference`).
 
-.. _runningXnt:
+.. _buildProperties:
 
-Running Xnt
------------
-
-Invoking Xnt from the command line is very simple and very similar to how other
-build tools are invoked (this was intentional).
-
-.. _defaultUse:
-
-Default Use
-~~~~~~~~~~~
-
-The most simplistic use of Xnt is as follows::
-
-    $ xnt
-
-This will attempt to invoke the `default` target in the current directory's
-`build.py`.
-
-.. _invokeTarget:
-
-Invoke a Target
-~~~~~~~~~~~~~~~
-
-To invoke a particular target, use::
-
-    $ xnt {target}
-
-Where the value of `{target}` is dependent on your particular `build.py` file.
-
-.. _specialTargets:
-
-Special Targets
-~~~~~~~~~~~~~~~
-
-"Special" targets (for lack of a better name) are targets that do not exist in
-the build script, but rather are a part of Xnt.
-
-Thus far, I have only defined one "special" target, ``list-targets`` (I don't
-think this name is going to change again ...).
-
-* ``list-targets`` does exactly what the name should suggest: it prints a list
-  of the targets found in the current directory's `build.py` script, along with
-  any docstrings that may be defined with them.
-
-Usage::
-
-    $ xnt list-targets
-
-.. _xntOptions:
-
-Options
-~~~~~~~
-
-Xnt also has a few "options" that may be provided along with a regular targets.
+Build Properties
+================
 
-Usage::
+As mentioned in :ref:`xntPropertiesParameters`, Xnt can accept parameters from
+the command line and pass them into the build file. Xnt doesn't necessarily
+expect the dictionary (named `properties`) to exist; but if you ever intend to
+use it, it will have to be defined one way or another (either to an empty
+dictionary or actually hold values). For example, to define an empty
+`properties` dictionary, one could write their build file as such::
 
-    $ xnt [options] [target]
+    #!/usr/bin/env python
 
-Where options can be any and all of the following (unless otherwise specified):
+    from xnt import target
 
-* ``-v``: add verbose output to the execution of Xnt
+    properties = {}
 
-* ``--version``: Print the version of Xnt and exit
+    @target
+    def foo():
+        #uses properties somehow
+        return 0
 
-* ``--usage``: Print version, license, usage information and quit. [I've
-  debatted between putting this as a special target and leaving it as an
-  option.. not sure which is better...]
+The hope for this feature is that it is easy to use because it borrows syntax
+from other build tools that you may already be familiar with.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 6ebb18e..9ecb765 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -26,6 +26,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   xenant
    buildfile
    taskreference
 
diff --git a/docs/source/xenant.rst b/docs/source/xenant.rst
new file mode 100644
index 0000000..86a26da
--- /dev/null
+++ b/docs/source/xenant.rst
@@ -0,0 +1,89 @@
+Running Xnt
+===========
+
+Invoking Xnt from the command line is very simple and very similar to how other
+build tools are invoked (this was intentional).
+
+.. _defaultUse:
+
+Default Use
+-----------
+
+The most simplistic use of Xnt is as follows::
+
+    $ xnt
+
+This will attempt to invoke the `default` target in the current directory's
+`build.py`.
+
+.. _invokeTarget:
+
+Invoke a Target
+---------------
+
+To invoke a particular target, use::
+
+    $ xnt {target}
+
+Where the value of `{target}` is dependent on your particular `build.py` file.
+
+.. _specialTargets:
+
+Special Targets
+---------------
+
+"Special" targets (for lack of a better name) are targets that do not exist in
+the build script, but rather are a part of Xnt.
+
+Thus far, I have only defined one "special" target, ``list-targets`` (I don't
+think this name is going to change again ...).
+
+* ``list-targets`` does exactly what the name should suggest: it prints a list
+  of the targets found in the current directory's `build.py` script, along with
+  any docstrings that may be defined with them.
+
+Usage::
+
+    $ xnt list-targets
+
+.. _xntOptions:
+
+Options
+-------
+
+Xnt also has a few "options" that may be provided along with a regular targets.
+
+Usage::
+
+    $ xnt [options] [target]
+
+Where options can be any and all of the following (unless otherwise specified):
+
+* ``-v``: add verbose output to the execution of Xnt
+
+* ``--version``: Print the version of Xnt and exit
+
+* ``--usage``: Print version, license, usage information and quit. [I've
+  debatted between putting this as a special target and leaving it as an
+  option.. not sure which is better...]
+
+.. _xntPropertiesParameters:
+
+Properties and Parameter Passing
+--------------------------------
+
+Xnt now has the ability to accept command line parameters and forward them to
+your `build.py` file. This can be useful for a number of reasons: flipping
+debug flags, deployment flags and the like or whatever else you can imagine.
+
+The general semantic for passing the parameters is as follows::
+
+    $ xnt [-D{name}={value}]+ [options] [target]
+
+*Notice:* the `-D` is used to distinguish values to be passed to the `build`
+file from regular options. You may specify as many parameters as you like and
+there is no other real ordering required to be parsed correctly. Just know,
+spaces are used to delimit arguments; if your passed value *must* have a space,
+remember to quote it.
+
+Please see :ref:`buildProperties` to see how this works on the `build.py` side.