[Misc][Installation] Improve source installation script and related documentation

docs/source/getting_started/installation.rst

@@ -84,6 +84,8 @@ Latest code can contain bugs and may not be stable. Please use it with caution.
 Build from source
 ==================
 
+.. _python-only-build:
+
 Python-only build (without compilation)
 ----------------------------------------
 
@@ -114,6 +116,23 @@ The script will:
 
 Now, you can edit the Python code in the current directory, and the changes will be reflected when you run vLLM.
 
+Once you have finished editing or want to install another vLLM wheel, you should exit the development environment using `the same script <https://github.com/vllm-project/vllm/blob/main/python_only_dev.py>`_ with the ``--quit-dev``(or ``-q`` for short) flag:
+
+.. code-block:: console
+
+    $ python python_only_dev.py --quit-dev
+
+The script with ``--quit-dev`` flag will:
+
+* Remove the symbolic link from the current directory to the vLLM package.
+* Restore the original vLLM package from the backup.
+
+If you update the vLLM wheel and want to rebuild from the source and make further edits, you will need to start `all above <#python-only-build>`_ over again.
+
+.. note::
+
+    There is a possibility that your source code may have a different commit ID compared to the latest vLLM wheel, which could potentially lead to unknown errors.
+    It is recommended to use the same commit ID for the source code as the vLLM wheel you have installed. Please refer to `the above section <#install-the-latest-code>`_ for instructions on how to install a specified wheel.
 
 Full build (with compilation)
 ---------------------------------

python_only_dev.py

@@ -1,10 +1,20 @@
 # enable python only development
 # copy compiled files to the current directory directly
 
+import argparse
 import os
 import shutil
 import subprocess
 import sys
+import warnings
+
+parser = argparse.ArgumentParser(
+    description="Development mode for python-only code")
+parser.add_argument('-q',
+                    '--quit-dev',
+                    action='store_true',
+                    help='Set the flag to quit development mode')
+args = parser.parse_args()
 
 # cannot directly `import vllm` , because it will try to
 # import from the current directory
@@ -37,18 +47,46 @@
     # "vllm/_version.py", # not available in nightly wheels yet
 ]
 
-for file in files_to_copy:
-    src = os.path.join(package_path, file)
-    dst = file
-    print(f"Copying {src} to {dst}")
-    shutil.copyfile(src, dst)
+# Try to create _version.py to avoid version related warning
+# Refer to https://github.com/vllm-project/vllm/pull/8771
+try:
+    from setuptools_scm import get_version
+    get_version(write_to="vllm/_version.py")
+except ImportError:
+    warnings.warn(
+        "To avoid warnings related to vllm._version, "
+        "you should install setuptools-scm by `pip install setuptools-scm`",
+        stacklevel=2)
+
+if not args.quit_dev:
+    for file in files_to_copy:
+        src = os.path.join(package_path, file)
+        dst = file
+        print(f"Copying {src} to {dst}")
+        shutil.copyfile(src, dst)
+
+    pre_built_vllm_path = os.path.join(package_path, "vllm")
+    tmp_path = os.path.join(package_path, "vllm_pre_built")
+    current_vllm_path = os.path.join(cwd, "vllm")
+
+    print(f"Renaming {pre_built_vllm_path} to {tmp_path} for backup")
+    os.rename(pre_built_vllm_path, tmp_path)
 
-pre_built_vllm_path = os.path.join(package_path, "vllm")
-tmp_path = os.path.join(package_path, "vllm_pre_built")
-current_vllm_path = os.path.join(cwd, "vllm")
+    print(f"Linking {current_vllm_path} to {pre_built_vllm_path}")
+    os.symlink(current_vllm_path, pre_built_vllm_path)
+else:
+    vllm_symlink_path = os.path.join(package_path, "vllm")
+    vllm_backup_path = os.path.join(package_path, "vllm_pre_built")
+    current_vllm_path = os.path.join(cwd, "vllm")
 
-print(f"Renaming {pre_built_vllm_path} to {tmp_path}")
-os.rename(pre_built_vllm_path, tmp_path)
+    print(f"Unlinking {current_vllm_path} to {vllm_symlink_path}")
+    assert os.path.islink(
+        vllm_symlink_path
+    ), f"not in dev mode: {vllm_symlink_path} is not a symbolic link"
+    assert current_vllm_path == os.readlink(
+        vllm_symlink_path
+    ), "current directory is not the source code of package"
+    os.unlink(vllm_symlink_path)
 
-print(f"linking {current_vllm_path} to {pre_built_vllm_path}")
-os.symlink(current_vllm_path, pre_built_vllm_path)
+    print(f"Recovering backup from {vllm_backup_path} to {vllm_symlink_path}")
+    os.rename(vllm_backup_path, vllm_symlink_path)