Restate installation and tutorial in terms of a virtualenv

Since we have things like "cd myproject" in the documentation,
we are assuming some knowledge of how the project is set up.
As the vast majority of projects will have import statements
in their env.py, restate this documentation in terms of a
virtual environment where the local project is installed
in editable mode.

Change-Id: I6a11c5077c02a00145cb882b43d6c9a7c986e375
Fixes: #625

diff --git a/docs/build/front.rst b/docs/build/front.rst
index d288472f7997898ab54561d657323fcd4ae2f2b8..ebafa1fa1b9536f7b64d2159503fe51ae572a373 100644 (file)
--- a/docs/build/front.rst
+++ b/docs/build/front.rst
@@ -19,16 +19,49 @@ The most recent published version of this documentation should be at https://ale
 Installation
 ============
 
-Install released versions of Alembic from the Python package index with `pip <http://pypi.python.org/pypi/pip>`_ or a similar tool::
+Installation of Alembic is typically local to a project setup and it is usually
+assumed that an approach like `virtual environments
+<https://docs.python.org/3/tutorial/venv.html>`_ are used, which would include
+that the target project also `has a setup.py script
+<https://packaging.python.org/tutorials/packaging-projects/>`_.
 
-    pip install alembic
+The documentation below is **only one kind of approach to installing Alembic for a
+project**; there are many such approaches.   The documentation below is
+provided only for those users who otherwise have no specific project setup
+chosen.
 
-Installation via source distribution is via the ``setup.py`` script::
+To build a virtual environment for a specific project, first we assume that
+`Python virtualenv <https://pypi.org/project/virtualenv/>`_ is installed
+systemwide.  Then::
 
-    python setup.py install
+    $ cd /path/to/your/project
+    $ virtualenv .venv
 
-The install will add the ``alembic`` command to the environment.  All operations with Alembic
-then proceed through the usage of this command.
+There is now a Python interpreter that you can access in
+``/path/to/your/project/.venv/bin/python``, as well as the `pip
+<http://pypi.python.org/pypi/pip>`_ installer tool in
+``/path/to/your/project/.venv/bin/pip``.
+
+We now install Alembic as follows::
+
+    $ /path/to/your/project/.venv/bin/pip install alembic
+
+The install will add the ``alembic`` command to the virtual environment.  All
+operations with Alembic in terms of this specific virtual environment will then
+proceed through the usage of this command, as in::
+
+    $ /path/to/your/project/.venv/bin/alembic init .
+
+Next, we ensure that the local project is also installed, in a development environment
+this would be in `editable mode <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_::
+
+    $ /path/to/your/project/.venv/bin/pip install -e .
+
+As a final step, the `virtualenv activate <https://virtualenv.pypa.io/en/latest/userguide/#activate-script>`_
+tool can be used so that the ``alembic`` command is available without any
+path information, within the context of the current shell::
+
+    $ source /path/to/your/project/.venv/bin/activate
 
 Dependencies
 ------------

diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst
index d423842fc032551af8d2dde1b932957cf7ac3e69..23f01576519193bc636bcb4a57662f2f32759831 100644 (file)
--- a/docs/build/tutorial.rst
+++ b/docs/build/tutorial.rst
@@ -7,6 +7,18 @@ scripts for a relational database, using SQLAlchemy as the underlying engine.
 This tutorial will provide a full introduction to the theory and usage of this tool.
 
 To begin, make sure Alembic is installed as described at :ref:`installation`.
+As stated in the linked document, it is usually preferable that Alembic is
+installed in the **same module / Python path as that of the target project**,
+usually using a `Python virtual environment
+<https://docs.python.org/3/tutorial/venv.html>`_, so that when the ``alembic``
+command is run, the Python script which is invoked by ``alembic``,  namely your
+project's ``env.py`` script, will have access to your application's models.
+This is not strictly necessary in all cases, however in the vast majority of
+cases is usually preferred.
+
+The tutorial below assumes the ``alembic`` command line utility is present in
+the local path and when invoked, will have access to the same Python module
+environment as that of the target project.
 
 The Migration Environment
 ==========================
@@ -72,7 +84,8 @@ Creating an Environment
 With a basic understanding of what the environment is, we can create one using ``alembic init``.
 This will create an environment using the "generic" template::
 
-    $ cd yourproject
+    $ cd /path/to/yourproject
+    $ source /path/to/yourproject/.venv/bin/activate   # assuming a local virtualenv
     $ alembic init alembic
 
 Where above, the ``init`` command was called to generate a migrations directory called ``alembic``::