Updating docs

CHANGELOG.rst

@@ -1,7 +1,7 @@
 Changelog
 ---------
 
-0.1 (2016-08-02)
+0.1 (2016-08-03)
 ~~~~~~~~~~~~~~~~
 
 Initial release.

README.rst

@@ -10,7 +10,9 @@ depman
 .. image:: https://readthedocs.org/projects/depman/badge/?version=latest
     :target: http://depman.readthedocs.org/en/latest/?badge=latest
 
-A lightweight dependency manager.
+A lightweight dependency manager for managing dependencies in different contexts. The use case driving development is that of distinguishing between development, testing, and production dependencies in a simple and unified way. However, the application is general purpose and can be used in any application requiring the management of dependencies in multiple contexts.
+
+Currently only dependencies resolved via `apt-get` and `pip` are supported.  However, support for other dependency types is planned for future releases (see `Future Features`_ for more details).
 
 Installation
 ------------
@@ -23,31 +25,44 @@ Usage
 -----
 ::
 
-    depman <command> [<scope> [<depfile>]]
+    usage: depman [-h] [-f <depfile>] <command> [<context>]
+
     A lightweight dependency manager.
 
-    Possible commands:
-	satisfy     Satisfy the dependencies specified in <depfile>
-        validate    Validate <depfile> only; do not change the state of the system
+    positional arguments:
+      <command>             'satisfy' satisfies the dependcies specified in
+			    <depfile>. 'validate' only validates <depfile> and
+			    does not perform any system operations
+      <context>             The dependency context to perform <command> on
 
-    Possible scopes:
-	all         Combines all possible scopes (default)
-	dev         Development dependencies
-	prod        Production dependencies
+    optional arguments:
+      -h, --help            show this help message and exit
+      -f <depfile>, --depfile <depfile>
+			    The requirements file to load
 
-    If no values are supplied, <depfile> defaults to "requirements.yml"
+If not supplied, `<depfile>` and `<context>` default to `requirements.yml` and `all`, respectively.
 
 Example(s)
 ----------
 
 Suppose you have the following `requirements.yml` in your current working directory::
 
+    includes:
+      dev:
+	- test
+
     dev:
       apt:
 	- libxml2-dev
 	- libxslt1-dev
       pip:
 	- lxml
+	- Sphinx
+
+    test:
+      pip:
+	- nose
+	- coverage
 
     prod:
       pip:
@@ -57,11 +72,17 @@ Suppose you have the following `requirements.yml` in your current working direct
 	- syn:
 	    always_upgrade: yes
 
-Running `depman satisfy dev` will install the development dependencies specified in `requirements.yml`.  First, it will use `apt-get` to install `libxml2-dev` and `libxslt1-dev` (both dependencies for `lxml`) and then use `pip` to install `lxml`.  In general, all `apt` dependencies are satisfied before `pip` dependencies.
+This file specifies three dependency contexts: `dev`, `test`, `prod`.  In general, any top-level key in `requirements.yml` specifies a dependency context.  The one exception to this rule is `includes`, which defines inclusion relationships between contexts.  In this example, the `dev` context includes the `test` context.  As such, when `depman satisfy test` is run at the command line, `depman` will invoke `pip` to install `nose` and `coverage`, if they do not exist on the system.  On the other hand, when `depman satisfy dev` is run at the command line, `depman` will first invoke `apt-get` to install `libxml1-dev` and `libxslt1-dev` and then invoke `pip` to install `lxml`, `Sphinx`, `nose`, and `coverage` (in general, `apt` dependencies are processed before `pip` dependencies).  Because `test` is "included" in `dev`, its dependencies are processed whenever `dev` is processed.
+
+`depman` also accepts the special context `all` as a valid command line parameter.  Running `depman satisfy all` causes `depman` to satisfy the dependencies in all of the defined depdenency contexts.  In this example, it would case `depman` to satisfy the dependcies for `dev`, `test`, and `prod`.  Running `depman satisfy` is equivalent to running `depman satisfy all`.
+
+Currently, only two dependency types are supported in any context: `apt` and `pip`.  However, support for other dependency types is planned for future releases (see `Future Features`_ for more details).
 
-Running `depman satisfy prod` will install the production dependencies specified in `requirements.yml`.  As there are only `pip` dependencies, it will use `pip` to install `gevent` (if either `gevent` is not currently installed, or if installed, has a version lower than 1.0.2), `texttable` (if `texttable`, regardless of version, is not currently installed), and `syn`.  Because the `always_upgrade` option is set, pip will always attempt to upgrade `syn` when `depman satisfy` is run.
+Dependencies are specified in each context, under each dependency type (i.e. `apt` or `pip`) as YAML list elements.  If the element is a string, the dependency in question will be treated as satisfied if some version of the package denoted by the string exists on the system.  For more detailed dependency requirements, the name of the package can be listed as the key to a YAML dictionary of dependency options.  This can be seen, for example, in the `gevent` dependency, in which a minimum version `1.0.2` is specified as a requirement.  Additionally, the `syn` package contains the `always_upgrade` option, which causes `depman` to always attempt to upgrade the package, regardless of the current version installed.
+
+In version 0.1, versioning features are only available for `pip` dependencies, but versioning options will be added to other dependency types in future releases.
 
-Running `depman satisfy` will satisfy both the development and production dependencies specified in `requirements.yml`.
+.. _Future Features:
 
 Future Features
 ---------------
@@ -71,9 +92,7 @@ The following features are planned for future releases:
 * Better versioning support (>=, ==, <=, etc.)
 * Support for apt versioning
 * apt PPA support
-* Better command-line argument parsing / usage information
-* YAML file validation
 * Dependency satisfaction optimizations
 * yum support
 * Support for scripted installs from source
-* Support for user-definable scopes
+* Export to requirements files for various package management systems