Improve installation and usage docs

.travis.yml

@@ -5,6 +5,7 @@ env:
   - TOXENV=py34
   - TOXENV=py35
   - TOXENV=linting
+  - TOXENV=docs
 
 python:
   - "3.5"

docs/conf.py

@@ -56,7 +56,7 @@
 
 # General information about the project.
 project = u'conda-devenv'
-copyright = u"2016, Edison Gustavo Muenz"
+copyright = u"2016, ESSS"
 
 # The version info for the project you're documenting, acts as replacement
 # for |version| and |release|, also used in various other places throughout
@@ -142,7 +142,7 @@
 # here, relative to this directory. They are copied after the builtin
 # static files, so a file named "default.css" will overwrite the builtin
 # "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page
 # bottom, using the given strftime format.
@@ -273,3 +273,11 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+suppress_warnings = [
+    # we include the README file into the docs, which contains nonlocal-uri to images (travis badge, etc)
+    'image.nonlocal_uri',
+    # our yaml files include jinja, which is not valid yaml; leave it like this
+    # anyway because some syntax highlight still works
+    'misc.highlighting_failure',
+]

docs/installation.rst

@@ -4,33 +4,13 @@
 Installation
 ============
 
-
-Stable release
---------------
-
 To install conda-devenv, run this command in your terminal:
 
 .. code-block:: console
 
     $ conda install conda-devenv -c conda-forge
 
 
-Or if you prefer PIP:
-
-.. code-block:: console
-
-    $ pip install conda-devenv
-
-
-Both methods are fine, as they will always install the most recent stable release.
-
-If you don't have `pip`_ installed, this `Python installation guide`_ can guide
-you through the process.
-
-.. _pip: https://pip.pypa.io
-.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
-
-
 From sources
 ------------
 

docs/usage.rst

@@ -2,16 +2,123 @@
 Usage
 =====
 
-To use conda-devenv::
+``conda-devenv`` works by creating ``conda`` environments from definitions found in ``environment.devenv.yml`` files.
 
-    conda devenv
+``environment.devenv.yml`` files are similar to ``environment.yml`` files processed by ``conda env``, with
+additional support for:
 
-In a directory containing a ``environment.devenv.yml`` file.
+Jinja2
+======
 
-This will execute the following:
+You can use `Jinja 2 <http://jinja.pocoo.org/docs/2.9/>`_ syntax at will, which lets you do all sort of things
+like conditionally add dependencies based on the current platform, change the default environment name
+based python version, etc. For example:
 
-1. Generate an ``environment.yml`` file.
-2. Call ``conda env update --prune --file environment.yml``
+.. code-block:: yaml
+
+    {% set conda_py = os.environ.get('CONDA_PY', '35') %}
+    name: web-ui-py{{ conda_py }}
+
+    dependencies:
+      {% if sys.platform.startswith('linux') %}
+      - gcc
+      {% endif %}
+
+
+The following variables are available in the Jira 2 namespace:
+
+* ``root``: this is the full path to the directory containing the ``environment.devenv.yml`` file;
+* ``os``: standard module;
+* ``sys``: standard module;
+* ``platform``: standard module;
+
+
+Environment Variables
+=====================
+
+It is possible to define environment variables that should be configured in the environment when activated.
+
+.. code-block:: yaml
+
+    environment:
+      PATH:
+        - {{ root }}/bin
+      PYTHONPATH:
+        - {{ root }}/source/python
+      DB_LOCATION: https://localhost/dev
+
+Environment variables defined in *list form* (like ``PATH`` and ``PYTHONPATH`` above) will **append** to existing
+variables, using the appropriate separator for the platform (``:`` on Linux/OSX and ``;`` on Windows).
+
+Environment variables defined as a single string (like ``DB_LOCATION`` above) will **overwrite** an existing
+variable with the same name.
+
+``conda-devenv`` restores the variables of the environment to their original state upon deactivation.
+
+Includes
+========
+
+It is possible to use *include* directives to include one or more ``environment.devenv.yml`` files. This merges all
+``dependencies`` and ``environment`` definitions into a single environment, which makes it a good solution to work
+in one or more repositories in development mode.
+
+For example:
+
+``/home/user/projects/core/environment.devenv.yml``:
+
+.. code-block:: yaml
+
+    name: core
+    dependencies:
+      - numpy
+      - pandas
+      - pytest
+      - invoke
+    environment:
+      PYTHONPATH:
+        - {{ root }}/source/python
+
+
+``/home/user/projects/web-ui/environment.devenv.yml``:
+
+.. code-block:: yaml
+
+    name: web-ui
+    includes:
+      - {{ root }}/../core/environment.devenv.yml
+    dependencies:
+      - flask
+      - jinja2
+    environment:
+      PYTHONPATH:
+        - {{ root }}/source/python
+      PATH:
+        - {{ root }}/bin
+
+In this setup, all the user has to do is executing ``conda devenv``:
+
+.. code-block:: console
+
+    $ cd ~/projects/web-ui
+    $ conda devenv
+
+This will create a ``conda`` environment named ``web-ui`` containing all the dependencies and environment variables
+defined in both files.
+
+How it works
+============
+
+Here's how ``conda-devenv`` works behind the scenes:
+
+1. Generate an ``environment.yml`` file in the same directory as the ``environment.devenv.yml`` file. The generated
+   ``environment.yml`` should **not** be added to VCS.
+2. Call ``conda env update --prune --file environment.yml``.
+3. Generate ``devenv-activate{.sh,.bat}`` and ``devenv-deactivate{.sh,.bat}`` scripts in ``$PREFIX/etc/conda/activate.d``
+   and ``$PREFIX/etc/conda/deactivate.d`` respectively which will set/unset the environment variables.
+
+
+Command-line reference
+======================
 
 Default options
 ---------------

setup.py

@@ -24,8 +24,7 @@
     version='0.9.0',
     description="Work with multiple projects in develop-mode using conda-env",
     long_description=readme + '\n\n' + history,
-    author="Edison Gustavo Muenz and others",
-    author_email='edisongustavo@gmail.com',
+    author="ESSS",
     url='https://github.com/ESSS/conda-devenv',
     packages=[
         'conda_devenv',
@@ -43,7 +42,7 @@
     zip_safe=False,
     keywords='conda_devenv',
     classifiers=[
-        'Development Status :: 2 - Pre-Alpha',
+        'Development Status :: 4 - Beta',
         'Intended Audience :: Developers',
         'License :: OSI Approved :: MIT License',
         'Natural Language :: English',

tox.ini

@@ -1,5 +1,16 @@
 [tox]
-envlist = py27, py34, py35, linting
+envlist =
+    py27
+    py34
+    py35
+    linting
+    docs
+
+[testenv]
+deps =
+    -r{toxinidir}/requirements_dev.txt
+commands =
+    py.test tests
 
 [testenv:linting]
 deps =
@@ -11,8 +22,13 @@ commands =
     flake8 conda_devenv
     rst-lint AUTHORS.rst CONTRIBUTING.rst HISTORY.rst README.rst
 
-[testenv]
-deps =
-    -r{toxinidir}/requirements_dev.txt
-commands =
-    py.test tests
+[testenv:docs]
+skipsdist=True
+usedevelop=True
+changedir=docs
+deps=
+    sphinx
+    PyYAML
+
+commands=
+    sphinx-build -W -b html . _build