From 20eb596e0cecb90a7c6ecc7e65f2511c0e0ee512 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Tue, 21 Mar 2017 16:37:55 -0300 Subject: [PATCH 1/5] Improve installation and usage docs * Remove pip install instructions * Add more information to usage --- docs/installation.rst | 20 ------- docs/usage.rst | 119 +++++++++++++++++++++++++++++++++++++++--- 2 files changed, 113 insertions(+), 26 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 393d35a..31914e0 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -4,10 +4,6 @@ Installation ============ - -Stable release --------------- - To install conda-devenv, run this command in your terminal: .. code-block:: console @@ -15,22 +11,6 @@ To install conda-devenv, run this command in your terminal: $ 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 ------------ diff --git a/docs/usage.rst b/docs/usage.rst index 88e4d49..4d52a30 100644 --- a/docs/usage.rst +++ b/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 `_ 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``; +* ``sys``; +* ``platform``; + + +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 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 --------------- From bc6c7973f415aef3385fb3a688886fdf3e57a3ce Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Tue, 21 Mar 2017 16:43:23 -0300 Subject: [PATCH 2/5] Generate docs during travis build to ensure they are correct --- .travis.yml | 1 + tox.ini | 28 ++++++++++++++++++++++------ 2 files changed, 23 insertions(+), 6 deletions(-) diff --git a/.travis.yml b/.travis.yml index d5a591f..3837842 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,6 +5,7 @@ env: - TOXENV=py34 - TOXENV=py35 - TOXENV=linting + - TOXENV=docs python: - "3.5" diff --git a/tox.ini b/tox.ini index 1ce5523..9d8c2b6 100644 --- a/tox.ini +++ b/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 From 7956f28a824611195e7f608957626caec0995ca1 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Tue, 21 Mar 2017 17:09:05 -0300 Subject: [PATCH 3/5] Suppress some warnings when generating docs --- docs/conf.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index e516da4..2ff8795 100755 --- a/docs/conf.py +++ b/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', +] From 7ffed07efab028c505ee750acbfae46d61014a8a Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Wed, 22 Mar 2017 08:54:46 -0300 Subject: [PATCH 4/5] Code review suggestions --- docs/usage.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index 4d52a30..75be2b5 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -28,9 +28,9 @@ based python version, etc. For example: 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``; -* ``sys``; -* ``platform``; +* ``os``: standard module; +* ``sys``: standard module; +* ``platform``: standard module; Environment Variables @@ -48,7 +48,7 @@ It is possible to define environment variables that should be configured in the 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 and ``;`` on Windows). +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. @@ -113,7 +113,7 @@ 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`` +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. From 426ab1d23dc7d07b91904fe89b3c6afba73c3d45 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Wed, 22 Mar 2017 08:56:37 -0300 Subject: [PATCH 5/5] Update author to ESSS and set status to Beta --- setup.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/setup.py b/setup.py index d5fe2a2..6592763 100644 --- a/setup.py +++ b/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',