Tweak docs about version_path_separator

diff --git a/alembic/templates/async/alembic.ini.mako b/alembic/templates/async/alembic.ini.mako
index fa44a8f8a5a609f8f01c3aaf08939a542ad41a1d..9afeb2d2940500d91e3f38681b3414659197967f 100644 (file)
--- a/alembic/templates/async/alembic.ini.mako
+++ b/alembic/templates/async/alembic.ini.mako
@@ -35,16 +35,18 @@ prepend_sys_path = .
 # version location specification; This defaults
 # to ${script_location}/versions.  When using multiple version
 # directories, initial revisions must be specified with --version-path.
-# The path separator used here should be the separator specified by "version_path_separator"
+# The path separator used here should be the separator specified by "version_path_separator" below.
 # version_locations = %(here)s/bar:%(here)s/bat:${script_location}/versions
 
 # version path separator; As mentioned above, this is the character used to split
-# version_locations. Valid values are:
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
 #
 # version_path_separator = :
 # version_path_separator = ;
 # version_path_separator = space
-version_path_separator = os  # default: use os.pathsep
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
 # the output encoding used when revision files
 # are written from script.py.mako

diff --git a/alembic/templates/generic/alembic.ini.mako b/alembic/templates/generic/alembic.ini.mako
index fa44a8f8a5a609f8f01c3aaf08939a542ad41a1d..9afeb2d2940500d91e3f38681b3414659197967f 100644 (file)
--- a/alembic/templates/generic/alembic.ini.mako
+++ b/alembic/templates/generic/alembic.ini.mako
@@ -35,16 +35,18 @@ prepend_sys_path = .
 # version location specification; This defaults
 # to ${script_location}/versions.  When using multiple version
 # directories, initial revisions must be specified with --version-path.
-# The path separator used here should be the separator specified by "version_path_separator"
+# The path separator used here should be the separator specified by "version_path_separator" below.
 # version_locations = %(here)s/bar:%(here)s/bat:${script_location}/versions
 
 # version path separator; As mentioned above, this is the character used to split
-# version_locations. Valid values are:
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
 #
 # version_path_separator = :
 # version_path_separator = ;
 # version_path_separator = space
-version_path_separator = os  # default: use os.pathsep
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
 # the output encoding used when revision files
 # are written from script.py.mako

diff --git a/alembic/templates/multidb/alembic.ini.mako b/alembic/templates/multidb/alembic.ini.mako
index 1f76ab563d2f3565b99a6b7bbe6cc5463e371d93..80c8d9fb4a32aefe4a1155c77a1fd893e7e9bc8a 100644 (file)
--- a/alembic/templates/multidb/alembic.ini.mako
+++ b/alembic/templates/multidb/alembic.ini.mako
@@ -35,16 +35,18 @@ prepend_sys_path = .
 # version location specification; This defaults
 # to ${script_location}/versions.  When using multiple version
 # directories, initial revisions must be specified with --version-path.
-# The path separator used here should be the separator specified by "version_path_separator"
+# The path separator used here should be the separator specified by "version_path_separator" below.
 # version_locations = %(here)s/bar:%(here)s/bat:${script_location}/versions
 
 # version path separator; As mentioned above, this is the character used to split
-# version_locations. Valid values are:
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
 #
 # version_path_separator = :
 # version_path_separator = ;
 # version_path_separator = space
-version_path_separator = os  # default: use os.pathsep
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
 # the output encoding used when revision files
 # are written from script.py.mako

diff --git a/alembic/templates/pylons/alembic.ini.mako b/alembic/templates/pylons/alembic.ini.mako
index c7313547813059304ba94e050dd2b097fa6f5146..bb425a600243f807f33e20c99a8c1a60abc59d4c 100644 (file)
--- a/alembic/templates/pylons/alembic.ini.mako
+++ b/alembic/templates/pylons/alembic.ini.mako
@@ -35,16 +35,18 @@ prepend_sys_path = .
 # version location specification; This defaults
 # to ${script_location}/versions.  When using multiple version
 # directories, initial revisions must be specified with --version-path.
-# The path separator used here should be the separator specified by "version_path_separator"
+# The path separator used here should be the separator specified by "version_path_separator" below.
 # version_locations = %(here)s/bar:%(here)s/bat:${script_location}/versions
 
 # version path separator; As mentioned above, this is the character used to split
-# version_locations. Valid values are:
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
 #
 # version_path_separator = :
 # version_path_separator = ;
 # version_path_separator = space
-version_path_separator = os  # default: use os.pathsep
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
 # the output encoding used when revision files
 # are written from script.py.mako
@@ -63,4 +65,4 @@ version_path_separator = os  # default: use os.pathsep
 
 pylons_config_file = ./development.ini
 
-# that's it !
\ No newline at end of file
+# that's it !

diff --git a/docs/build/branches.rst b/docs/build/branches.rst
index f3e5f4b921562a32e1004f358b9f060623efc562..0eed96d115f4ce6e09125573166f22ccf7b9ba44 100644 (file)
--- a/docs/build/branches.rst
+++ b/docs/build/branches.rst
@@ -521,11 +521,12 @@ that module.  So to start out, we can edit ``alembic.ini`` to refer
 to multiple directories;  we'll also state the current ``versions``
 directory as one of them::
 
+  # A separator for the location paths must be defined first.
+  version_path_separator = os  # Use os.pathsep.
   # version location specification; this defaults
   # to foo/versions.  When using multiple version
   # directories, initial revisions must be specified with --version-path
-  version_path_separator = space
-  version_locations = %(here)s/model/networking %(here)s/alembic/versions
+  version_locations = %(here)s/model/networking:%(here)s/alembic/versions
 
 The new directory ``%(here)s/model/networking`` is in terms of where
 the ``alembic.ini`` file is, as we are using the symbol ``%(here)s`` which

diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst
index cf3fe192837c6a03365e363b9edb097aad9eb020..fffd0742347597b223baa6a1c66a917f84226b79 100644 (file)
--- a/docs/build/tutorial.rst
+++ b/docs/build/tutorial.rst
@@ -162,16 +162,18 @@ The file generated with the "generic" configuration looks like::
     # version location specification; This defaults
     # to ${script_location}/versions.  When using multiple version
     # directories, initial revisions must be specified with --version-path.
-    # The path separator used here should be the separator specified by "version_path_separator"
+    # The path separator used here should be the separator specified by "version_path_separator" below.
     # version_locations = %(here)s/bar:%(here)s/bat:${script_location}/versions
 
     # version path separator; As mentioned above, this is the character used to split
-    # version_locations. Valid values are:
+    # version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+    # If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+    # Valid values for version_path_separator are:
     #
     # version_path_separator = :
     # version_path_separator = ;
     # version_path_separator = space
-    version_path_separator = os  # default: use os.pathsep
+    version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
     # the output encoding used when revision files
     # are written from script.py.mako
@@ -307,6 +309,10 @@ This file contains the following features:
   allow revisions to exist in multiple directories simultaneously.
   See :ref:`multiple_bases` for examples.
 
+* ``version_path_separator`` - a separator of ``version_locations`` paths.
+  It should be defined if multiple ``version_locations`` is used.
+  See :ref:`multiple_bases` for examples.
+
 * ``output_encoding`` - the encoding to use when Alembic writes the
   ``script.py.mako`` file into a new migration file.  Defaults to ``'utf-8'``.