changes for 0.1a4

.gitignore

@@ -1,3 +1,4 @@
+*.sublime-workspace
 .reqwire.lock
 
 # Byte-compiled / optimized / DLL files
@@ -11,7 +12,7 @@ __pycache__/
 # Distribution / packaging
 .Python
 env/
-./build/
+build/
 develop-eggs/
 dist/
 downloads/

MANIFEST.in

@@ -1 +1,9 @@
-include README.rst
+include AUTHORS
+include LICENSE
+include MANIFEST.in
+include README.rst
+graft docs
+graft tests
+graft requirements/lck
+global-exclude __pycache__
+global-exclude *.py[co]

docs/source/conf.py

@@ -9,6 +9,7 @@
 
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',

docs/source/guide.rst

@@ -1,4 +1,160 @@
 User Guide
 ==========
 
-*Coming soon.* For now, just use ``--help``.
+.. contents::
+   :backlinks: none
+
+Directory Structure
+-------------------
+
+Reqwire introduces a **requirements base directory** to the root of your
+project, and two subdirectories: a **source** directory and a **build**
+directory. By default, the source directory is named *src*, and the
+build directory is named *lck* (for lock, as built requirements.txt
+files are analogous to the lock files of many other package managers).
+
+The names for all three of these directories are configurable, by
+passing the ``-d|--directory``, ``--source-directory``, and
+``--build-directory`` options, respectively, to ``reqwire``, **before**
+any commands. For example:
+
+.. code-block:: shell
+
+   $ reqwire -d req --source-directory=_src --build-directory=_build build -a
+   # ...or...
+   $ export REQWIRE_DIR_BASE=req
+   $ export REQWIRE_DIR_SOURCE=_src
+   $ export REQWIRE_DIR_BUILD=_build
+   $ reqwire build -a
+
+Packaging and Version Control
+-----------------------------
+
+Ideally, the requirements directory should be located in a project's
+root directory, and both source and build directories added to version
+control. Depending on the project and target audience, it might make
+sense to copy or symlink the primary, built requirements tag (usually
+``main``) to a ``requirements.txt`` file in the project root.
+
+If you're distributing a Python package, it might be useful to Include
+the *build directory* in your `MANIFEST.in`_ file. This can be simply
+achieved with ``graft``::
+
+  graft requirements/lck
+
+Take care to ensure that the built requirements directory is not
+ignored by ``.gitignore``, ``.hgignore``, etc. This should not be a
+problem if using the default build directory name (*lck*).
+
+.. _MANIFEST.in: https://docs.python.org/3.6/distutils/sourcedist.html#specifying-the-files-to-distribute
+
+Tag Organization
+----------------
+
+The purpose of **tags** in reqwire is to provide logical separation of
+package requirements based on the environment they target. For instance,
+`Sphinx`_ is likely only needed when building documentation, and not at
+runtime. `pytest`_ and pytest plugins are only required in a continuous
+integration (CI) environment, and so on.
+
+Traditionally, you would use tools like `tox`_, and end up maintaining
+requirements in more than one location, and likely not bother to
+pin versions or declare sub-dependencies. reqwire makes it convenient
+for package maintainers to quickly generate concrete, first-level
+requirements, which should hopefully encourage best practices across
+all environments.
+
+.. _Sphinx: http://www.sphinx-doc.org/en/1.5.1/
+.. _pytest: http://doc.pytest.org/en/latest/
+.. _tox: http://tox.readthedocs.io/en/latest/config.html?highlight=deps#confval-deps=MULTI-LINE-LIST
+
+Command Reference
+-----------------
+
+reqwire add
+~~~~~~~~~~~
+
+* ``reqwire add [specifier]...``
+
+  Installs packages to the local environment and updates one or more
+  tagged requirement source files.
+
+  If no other parameters are given, this command will...
+
+  * Resolve the latest version of the provided package(s), unless a
+    pinned version is provided.
+  * Install the package with **pip**.
+  * Add the requirement to the ``main`` tag.
+
+* ``reqwire add -b [specifier]...``
+
+  Calls :ref:`reqwire build` for each tag provided (or ``main`` if no
+  tags were provided).
+
+* ``reqwire add [-t <tag name>]... [specifier]...``
+
+  Saves packages to the specified requirement tag(s).
+
+* ``reqwire add --no-install [specifier]...``
+
+  Skips package installation.
+
+* ``reqwire add --no-resolve-canonical-names [specifier]...``
+
+  By default, reqwire will search the Python package index for an exact
+  match of package names, and use the canonical name (i.e. casing) for
+  each specifier.
+
+  Passing this flag results in the user-provided package being saved to
+  requirement source files.
+
+* ``reqwire add --no-resolve-versions [specifier]...``
+
+  By default, reqwire will resolve the latest version for each specifier
+  provided.
+
+  Passing this flag allows for adding non-pinned packages to requirement
+  source files. In most cases, this is not recommended even though the
+  resulting requirement lock files will resolve to latest versions anyway.
+
+* ``reqwire add --pre [specifier]...``
+
+  Includes prerelease versions when resolving versions.
+
+reqwire build
+~~~~~~~~~~~~~
+
+* ``reqwire build -a``
+
+  Builds all tags.
+
+* ``reqwire build -t TAG``
+
+  Builds one or more tags.
+
+reqwire init
+~~~~~~~~~~~~
+
+* ``reqwire init``
+
+  Scaffolds a requirements directory in the current directory.
+
+* ``reqwire init -f``
+
+  Scaffolds a requirements directory and overwrites any default tag
+  names, and ignores pre-existing directories.
+
+* ``reqwire init --index-url=INDEX_URL``
+
+  Changes the base URL written to requirement source files.
+
+* ``reqwire init -t TAG``
+
+  Creates the given tag names as requirement source files.
+
+  If not provided, the tags ``docs``, ``main``, ``qa``, and ``test``
+  will get created.
+
+* ``reqwire init --extra-index-url INDEX_URL``
+
+  Adds ``extra-index-url`` options to requirement source files.

docs/source/quickstart.rst

@@ -24,7 +24,7 @@ Usage
    This will scaffold out a requirements directory::
 
        requirements/
-       ├── build
+       ├── lck
        └── src
            ├── main.in
            ├── qa.in

docs/source/release_notes.rst

@@ -4,6 +4,18 @@ Release Notes
 .. contents::
    :backlinks: none
 
+
+0.1a4
+-----
+
+* Corrected package setup to include `sh <https://github.com/amoffat/sh>`_
+  as an installation dependency.
+* Updated ``MANIFEST.in`` to include additional files in distribution.
+* Made source and build directories configurable through command-line
+  and environment variables.
+* File headers now include modelines for Vim and Sublime Text (via
+  `STEmacsModelines <https://github.com/kvs/STEmacsModelines>`_).
+
 0.1a3 (12/11/16)
 ----------------
 

requirements/lck/docs.txt

@@ -0,0 +1,53 @@
+# -*- mode: requirementstxt -*-
+# vim: set ft=requirements
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+#    pip-compile --generate-hashes --output-file /tmp/tmpxsbctovn requirements/src/docs.in
+#
+alabaster==0.7.9 \
+    --hash=sha256:47afd43b08a4ecaa45e3496e139a193ce364571e7e10c6a87ca1a4c57eb7ea08 \
+    --hash=sha256:d3e64a74919373d6d4d1d36bd717206584cb64cbb0532dfce3bc2081cba6817b  # via sphinx
+babel==2.3.4 \
+    --hash=sha256:3318ed2960240d61cbc6558858ee00c10eed77a6508c4d1ed8e6f7f48399c975 \
+    --hash=sha256:c535c4403802f6eb38173cd4863e419e2274921a01a8aad8a5b497c131c62875  # via sphinx
+docutils==0.13.1 \
+    --hash=sha256:718c0f5fb677be0f34b781e04241c4067cbd9327b66bdd8e763201130f5175be \
+    --hash=sha256:cb3ebcb09242804f84bdbf0b26504077a054da6772c6f4d625f335cc53ebf94d  # via sphinx
+imagesize==0.7.1 \
+    --hash=sha256:0ab2c62b87987e3252f89d30b7cedbec12a01af9274af9ffa48108f2c13c6062 \
+    --hash=sha256:6ebdc9e0ad188f9d1b2cdd9bc59cbe42bf931875e829e7a595e6b3abdc05cdfb  # via sphinx
+Jinja2==2.8 \
+    --hash=sha256:1cc03ef32b64be19e0a5b54578dd790906a34943fe9102cfdae0d4495bd536b4 \
+    --hash=sha256:bc1ff2ff88dbfacefde4ddde471d1417d3b304e8df103a7a9437d47269201bf4  # via sphinx
+MarkupSafe==0.23 \
+    --hash=sha256:a4ec1aff59b95a14b45eb2e23761a0179e98319da5a7eb76b56ea8cdc7b871c3  # via jinja2
+pockets==0.3.1 \
+    --hash=sha256:7c1246b3a5a08e85256af13fa239f5bf8dc9bf78b690472e02702b341dad4a78 \
+    --hash=sha256:ec7d1aa5c4b677e2ad9c0bf1f86a8cac67946f9919e4cc958ccb872b44315bd0  # via sphinxcontrib-napoleon
+Pygments==2.1.3 \
+    --hash=sha256:485602129949b14247e8b124d28af4654dffbd076537c4a9c44a538a2c1755b7 \
+    --hash=sha256:88e4c8a91b2af5962bfa5ea2447ec6dd357018e86e94c7d14bd8cacbc5b55d81  # via sphinx
+pytz==2016.10 \
+    --hash=sha256:7016b2c4fa075c564b81c37a252a5fccf60d8964aa31b7f5eae59aeb594ae02b \
+    --hash=sha256:9a43e20aa537cfad8fe7a1715165c91cb4a6935d40947f2d070e4c80f2dcd22b \
+    --hash=sha256:a1ea35e87a63c7825846d5b5c81d23d668e8a102d3b1b465ce95afe1b3a2e065 \
+    --hash=sha256:aafbf066975fe217ed49d7d197b26903d3b43e9ca2aa6ba0a211081f13c41917  # via babel
+requests==2.12.4 \
+    --hash=sha256:000748df49e087784441b2621c50fb81046c5c8e80e0d91674ffad65b9e13844 \
+    --hash=sha256:ed98431a0631e309bb4b63c81d561c1654822cb103de1ac7b47e45c26be7ae34  # via sphinx
+six==1.10.0 \
+    --hash=sha256:0ff78c403d9bccf5a425a6d31a12aa6b47f1c21ca4dc2573a7e2f32a97335eb1 \
+    --hash=sha256:105f8d68616f8248e24bf0e9372ef04d3cc10104f1980f54d57b2ce73a5ad56a  # via pockets, sphinx, sphinxcontrib-napoleon
+snowballstemmer==1.2.1 \
+    --hash=sha256:919f26a68b2c17a7634da993d91339e288964f93c274f1343e3bbbe2096e1128 \
+    --hash=sha256:9f3bcd3c401c3e862ec0ebe6d2c069ebc012ce142cce209c098ccb5b09136e89  # via sphinx
+sphinx-md-theme==0.1a2 \
+    --hash=sha256:f8350430cc594cf305ed44f357d1296d7920b8f3f6a28e51a8bad45200447882
+Sphinx==1.5 \
+    --hash=sha256:1c52ac7696c4d37bb7bc59c58df81756928816e88624ba625f12082a9e9eb8f9 \
+    --hash=sha256:63997e0c9216185ae7b583a5e87a0619a172171b840d70b9ff7153f99a3d7fbf
+sphinxcontrib-napoleon==0.6.0 \
+    --hash=sha256:45aeb259eeecd6a641fcea45adb0a0268bbe92117ab52e7c919cd6bfc36fe548 \
+    --hash=sha256:7ea8d97e9b4342613e73c55bdeee910cea32235a6cb30b51a8ad0390890d1a2f