Discuss requirements.txt, and requirment specification arguments

docs/Makefile

@@ -3,7 +3,7 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
 
-DEPS          = _build/commands.inc
+DEPS          = _build/requirements.inc _build/commands.inc
 
 
 # User-friendly check for sphinx-build

docs/commands.py

@@ -19,11 +19,16 @@ def get_sub_action(parser):
 parser = get_parser()
 
 usage = parser.format_usage().replace('usage:', '')
-print '''.. _cli_vee:
+print '''
 
 top-level
 ---------
 
+.. _cli_vee:
+
+``vee``
+~~~~~~~
+
 ::
 
 '''
@@ -46,6 +51,8 @@ def get_sub_action(parser):
             continue
 
         if not did_header:
+            print '.. _cli_%s:' % group_name.replace(' ', '_')
+            print
             print group_name
             print '-' * len(group_name)
             print

docs/commands.rst

@@ -3,8 +3,5 @@
 Command-Line Interface
 ======================
 
-.. warning:: Very incomplete; please run ``vee [COMMAND] --help`` for more.
-
-
 .. include:: _build/commands.inc
 

docs/concepts.rst

@@ -72,6 +72,66 @@ A requirement is specification of a package that we would like to have installed
 in an environment. These are still represented via the :class:`Package` class.
 
 
+.. _requirements:
+
+Requirement Specification
+-------------------------
+
+Requirements are specified via a series of command-line-like arguments.
+The first is a URL, which may be HTTP, common git formats, or VEE-specific, e.g.:
+
+- ``http://cython.org/release/Cython-0.22.tar.gz``
+- ``git+git@git.westernx:westernx/sitetools``
+- ``pypi:pyyaml``
+
+The requirements are further refined by the following arguments:
+
+.. include:: _build/requirements.inc
+
+These may be passed to individual commands, e.g.::
+
+    vee link pypi:pyyaml --revision=3.11
+
+or via a ``requirements.txt`` file, which contains a list of requirements.
+
+
+.. _requirements_txt:
+
+``requirements.txt``
+--------------------
+
+The requirements file may also include:
+
+    - Headers, which are lines formatted like ``Header: Value``, e.g.::
+
+        Name: WesternX
+        Version: 0.43.23
+        Vee-Revision: 0.1-dev+4254bc1
+
+    - Comments beginning with ``#``;
+    - Basic control flow, starting with ``%``, e.g.::
+
+        # For the Shotgun cache:
+        % if os.environ.get('VEEINCLUDE_SGCACHE'):
+            git+git@git.westernx:westernx/sgapi --revision=6da9d1c5
+            git+git@git.westernx:westernx/sgcache --revision=cd673656
+            git+git@git.westernx:westernx/sgevents --revision=a58e61c5
+        % endif
+
+
+.. _env_repo:
+
+Environment Repository
+----------------------
+
+An environment repository is a git repository which contains (at a minimum)
+a :ref:`requirements_txt` file.
+
+They are managed by the :ref:`cli_vee_repo` command.
+
+
+
+
 .. _exec_env:
 
 Execution Environment

docs/requirements.py

@@ -0,0 +1,34 @@
+
+import os
+import sys
+from argparse import _SubParsersAction, RawDescriptionHelpFormatter, SUPPRESS
+
+sys.path.append(os.path.abspath(os.path.join(__file__, '..', '..')))
+
+
+from vee.package import requirement_parser as parser
+
+formatter = RawDescriptionHelpFormatter('requirements.txt')
+
+
+for action in parser._actions:
+
+    if action.dest in ('url', ):
+        continue
+    if action.help == SUPPRESS:
+        continue
+
+    print '.. _requirement_arg_%s:' % action.dest
+    print
+
+    lines = formatter._format_action(action).splitlines()
+
+    print '``%s``' % lines[0]
+    #print '~' * (4 + len(lines[0]))
+    print
+    print '\n'.join(lines[1:])
+    print
+
+#for line in parser.format_help().splitlines():
+#    print '    ' + line
+

docs/workflow.rst

@@ -20,8 +20,8 @@ Basic Installation
     sudo chmod -R g=rwXs,o=rwX $VEE
 
 
-User Repo Workflow
-------------------
+User Workflow
+-------------
 
 .. code-block:: bash
     
@@ -49,41 +49,20 @@ User Repo Workflow
     vee upgrade
 
 
-User Manual Workflow
---------------------
-
-.. code-block:: bash
-
-    # Install some individual packages into the default environment.
-    # These will be lost upon the next "upgrade".
-    vee link homebrew+sqlite
-    vee link homebrew+ffmpeg --configuration='--with-faac'
-    vee link git+https://github.com/shotgunsoftware/python-api.git --name shotgun_api3
-    vee link --force https://github.com/westernx/sgmock/archive/master.zip --install-name sgmock/0.1
-    vee link git+git@git.westernx:westernx/sgsession
-
-    # Link a few packages into an "example" environment.
-    vee link -e example examples/basic.txt
-
-    # Execute within the "example" environment.
-    vee exec -e example python -c 'import sgmock; print sgmock'
-
 
 Developer Workflow
 ------------------
 
-.. warning:: This is still in heavy development.
-
 .. code-block:: bash
 
-    # Specify where you want your dev packages to be, if not in $VEE.
+    # Specify where you want your dev packages to be, if not in $VEE/dev.
     export VEE_DEV=~/dev
 
-    # Install a package for development. This must be a pacakge that is
+    # Install a package for development. This must be a package that is
     # referred to by the default repository.
     vee develop install PACKAGE
 
-    cd ~/dev/$package
+    cd ~/dev/PACKAGE
 
     # Develop here; use `dev` to run in the dev environment.
     dev MY_COMMAND
@@ -93,11 +72,34 @@ Developer Workflow
 
     # Commit your changes to the VEE repo.
     vee add PACKAGE
-    vee commit --patch -m 'Did something to PACAKGE.'
+    vee commit --patch -m 'Did something to PACKAGE.'
 
     # Test locally.
     vee upgrade
     MY_COMMAND
 
     # Push out the package, and repo.
+    git push
     vee push
+
+
+
+Manual Workflow
+---------------
+
+.. code-block:: bash
+
+    # Install some individual packages into the default environment.
+    # These will be lost upon the next "upgrade".
+    vee link homebrew+sqlite
+    vee link homebrew+ffmpeg --configuration='--with-faac'
+    vee link git+https://github.com/shotgunsoftware/python-api.git --name shotgun_api3
+    vee link --force https://github.com/westernx/sgmock/archive/master.zip --install-name sgmock/0.1
+    vee link git+git@git.westernx:westernx/sgsession
+
+    # Link a few packages into an "example" environment.
+    vee link -e example examples/basic.txt
+
+    # Execute within the "example" environment.
+    vee exec -e example python -c 'import sgmock; print sgmock'
+