From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 16 Nov 2019 15:25:38 +0000 (-0500)
Subject: Add some extra rationale for project-local setup
X-Git-Tag: rel_1_3_2~5
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=177c3de5a7c845bf31a749dc379d84804e405a92;p=thirdparty%2Fsqlalchemy%2Falembic.git

Add some extra rationale for project-local setup

Change-Id: I1c191e0a7189f911128ab8a1363ea821dcc15257
---

diff --git a/docs/build/front.rst b/docs/build/front.rst
index ebafa1fa..f5a6f059 100644
--- a/docs/build/front.rst
+++ b/docs/build/front.rst
@@ -25,6 +25,18 @@ assumed that an approach like `virtual environments
 that the target project also `has a setup.py script
 <https://packaging.python.org/tutorials/packaging-projects/>`_.
 
+.. note::
+
+    While the ``alembic`` command line tool runs perfectly fine no matter where
+    its installed, the rationale for project-local setup is that the Alembic
+    command line tool runs most of its key operations through a Python file
+    ``env.py`` that is established as part of a project's setup when the
+    ``alembic init`` command is run for that project;  the purpose of
+    ``env.py`` is to establish database connectivity and optionally model
+    definitions for the migration process, the latter of which in particular
+    usually rely upon being able to import the modules of the project itself.
+
+
 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