Add unit test, create a section about venv names

in advanced docs.

docs/advanced.rst

@@ -558,10 +558,19 @@ wherever you want, e.g.::
 
 In addition, you can also have Pipenv stick the virtualenv in ``project/.venv`` by setting the ``PIPENV_VENV_IN_PROJECT`` environment variable.
 
-☤ Custom Virtual Environment Name
+☤ Virtual Environment Name
 -------------------------------------
 
-Pipenv supports a custom name for the virtual environment set at ``PIPENV_CUSTOM_VENV_NAME``.  by default the venv will be named after the project directory.
+The virtualenv name created by Pipenv may be different from what you were expecting.
+Dangerous characters (i.e. ``$`!*@"`` as well as space, line feed, carriage return,
+and tab) are converted to underscores. Additionally, the full path to the current
+folder is encoded into a "slug value" and appended to ensure the virtualenv name
+is unique.
+
+Pipenv supports a arbitrary custom name for the virtual environment set at ``PIPENV_CUSTOM_VENV_NAME``.
+
+The logical place to specify this would be in a user's ``.env`` file in the root of the project, which gets loaded by pipenv when it is invoked.
+
 
 ☤ Testing Projects
 ------------------

docs/basics.rst

@@ -313,12 +313,6 @@ The user can provide these additional parameters:
                  **destructive** and will delete your current virtualenv before replacing
                  it with an appropriately versioned one.
 
-    .. note:: The virtualenv created by Pipenv may be different from what you were expecting.
-              Dangerous characters (i.e. ``$`!*@"`` as well as space, line feed, carriage return,
-              and tab) are converted to underscores. Additionally, the full path to the current
-              folder is encoded into a "slug value" and appended to ensure the virtualenv name
-              is unique.
-
     - ``--dev`` — Install both ``develop`` and ``default`` packages from ``Pipfile``.
     - ``--system`` — Use the system ``pip`` command rather than the one from your virtualenv.
     - ``--deploy`` — Make sure the packages are properly locked in Pipfile.lock, and abort if the lock file is out-of-date.

tests/integration/test_dot_venv.py

@@ -161,3 +161,18 @@ def test_venv_in_project_default_when_venv_exists(PipenvInstance):
 
             assert venv_loc.joinpath('.project').exists()
             assert venv_loc == Path(venv_path)
+
+
+@pytest.mark.dotenv
+def test_venv_name_accepts_custom_name_environment_variable(PipenvInstance):
+    """Tests that virtualenv reads PIPENV_CUSTOM_VENV_NAME and accepts it as a name
+    """
+    with PipenvInstance(chdir=True, venv_in_project=False) as p:
+        test_name = "sensible_custom_venv_name"
+        os.environ['PIPENV_CUSTOM_VENV_NAME'] = test_name
+        c = p.pipenv('install')
+        assert c.returncode == 0
+        c = p.pipenv('--venv')
+        assert c.returncode == 0
+        venv_path = c.stdout.strip()
+        assert test_name == Path(venv_path).parts[-1]