[Doctest] add installation doctest

Co-authored-by: wangli <wangli858794774@gmail.com>
Signed-off-by: Yikun Jiang <yikunkero@gmail.com>

Author: Yikun

.github/workflows/vllm_ascend_doctest.yaml

@@ -46,7 +46,7 @@ jobs:
       # Each version should be tested
       fail-fast: false
       matrix:
-        vllm_verison: [main, v0.7.3-dev, main-openeuler, v0.7.3-dev-openeuler]
+        vllm_verison: [0.9.1-dev, 0.9.1-dev-openeuler, main, main-openeuler]
     name: vLLM Ascend test
     runs-on: linux-arm64-npu-1
     container:
@@ -70,13 +70,13 @@ jobs:
         run: |
           sed -i 's|ports.ubuntu.com|mirrors.tuna.tsinghua.edu.cn|g' /etc/apt/sources.list
           apt-get update -y
-          apt install git curl -y
+          apt install -y gcc g++ libnuma-dev git curl jq
 
       - name: Config OS mirrors - openEuler
         if: ${{ endsWith(matrix.vllm_verison, '-openeuler') }}
         run: |
           yum update -y
-          yum install git curl -y
+          yum install -y gcc g++ numactl-devel git curl jq
 
       - name: Config pip mirrors
         run: |
@@ -88,11 +88,12 @@ jobs:
       - name: Run vllm-ascend/tests/e2e/run_doctests.sh
         run: |
           # PWD: /__w/vllm-ascend/vllm-ascend
-          # Address old branch like v0.7.3:
-          if [ ! -d /vllm-workspace/vllm-ascend/tests/e2e ]; then
-            echo "Warning: the doctest path doesn't exists, copy now"
-            cp -r tests/e2e /vllm-workspace/vllm-ascend/tests/
-          fi
+          echo "Replacing /vllm-workspace/vllm-ascend/tests/e2e ..."
+          rm -rf /vllm-workspace/vllm-ascend/tests/e2e
+          mkdir -p /vllm-workspace/vllm-ascend/tests
+          cp -r tests/e2e /vllm-workspace/vllm-ascend/tests/
+          # Remove this after conf.py merged
+          cp docs/source/conf.py /vllm-workspace/vllm-ascend/docs/source/
 
           # Simulate container to enter directory
           cd /workspace

docs/source/conf.py

@@ -23,6 +23,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import json
 import os
 
 # import sys
@@ -133,3 +134,7 @@
 
 def setup(app):
     pass
+
+
+if __name__ == "__main__":
+    print(json.dumps(myst_substitutions))

docs/source/installation.md

@@ -245,7 +245,8 @@ for output in outputs:
 Then run:
 
 ```bash
-# export VLLM_USE_MODELSCOPE=true to speed up download if huggingface is not reachable.
+# Try `export VLLM_USE_MODELSCOPE=true` and `pip install modelscope`
+# to speed up download if huggingface is not reachable.
 python example.py
 ```
 

tests/e2e/common.sh

@@ -45,7 +45,30 @@ function wait_for_exit() {
     _info "===> Wait for ${VLLM_PID} to exit."
     sleep 1
   done
-  _info "===> Wait for ${VLLM_PID} to exit."
+  _info "===> Process ${VLLM_PID} has exited."
+}
+
+VENV_PATH=/tmp/vllm_venv
+
+function clean_venv() {
+  if [[ -n "$VENV_PATH" && -d "$VENV_PATH" ]]; then
+    _info "Cleaning up default virtual env path: ${VENV_PATH}"
+    deactivate || true
+    rm -rf "$VENV_PATH"
+  fi
+}
+
+function create_vllm_venv() {
+  # make a clean env path
+  clean_venv
+  _info "Creating vllm virtual environment at ${VENV_PATH}"
+  python3 -m venv ${VENV_PATH}
+  source ${VENV_PATH}/bin/activate
+}
+
+function get_version() {
+  local VERSION_NAME="$1"
+  python3 "${SCRIPT_DIR}/../../docs/source/conf.py" | jq .${VERSION_NAME} | tr -d '"'
 }
 
 SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)

tests/e2e/doctests/001-quickstart-test.sh

@@ -23,13 +23,11 @@ function simple_test() {
 }
 
 function quickstart_offline_test() {
-  export VLLM_USE_MODELSCOPE=true
   # Do real script test
   python3 "${SCRIPT_DIR}/../../examples/offline_inference_npu.py"
 }
 
 function quickstart_online_test() {
-  export VLLM_USE_MODELSCOPE=true
   vllm serve Qwen/Qwen2.5-0.5B-Instruct &
   wait_url_ready "vllm serve" "localhost:8000/v1/models"
   # Do real curl test

tests/e2e/doctests/002-pip-binary-installation-test.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+#
+# Copyright (c) 2025 Huawei Technologies Co., Ltd. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# This file is a part of the vllm-ascend project.
+#
+trap clean_venv EXIT
+
+function install_binary_test() {
+
+    create_vllm_venv
+
+    PIP_VLLM_VERSION=$(get_version pip_vllm_version)
+    PIP_VLLM_ASCEND_VERSION=$(get_version pip_vllm_ascend_version)
+    _info "====> Install vllm==${PIP_VLLM_VERSION} and vllm-ascend ${PIP_VLLM_ASCEND_VERSION}"
+
+    pip install vllm=="$(get_version pip_vllm_version)"
+    pip install vllm-ascend=="$(get_version pip_vllm_ascend_version)"
+
+    pip list | grep vllm
+
+    # Verify the installation
+    _info "====> Run offline example test"
+    pip install modelscope
+    python3 "${SCRIPT_DIR}/../../examples/offline_inference_npu.py"
+
+}
+
+_info "====> Start install_binary_test"
+install_binary_test

tests/e2e/run_doctests.sh

@@ -21,7 +21,13 @@ set -eo errexit
 
 . $(dirname "$0")/common.sh
 
+export VLLM_USE_MODELSCOPE=true
+export VLLM_LOGGING_LEVEL=ERROR
+
 _info "====> Start Quickstart test"
 . "${SCRIPT_DIR}/doctests/001-quickstart-test.sh"
 
+_info "====> Start pip binary installation test"
+. "${SCRIPT_DIR}/doctests/002-pip-binary-installation-test.sh"
+
 _info "Doctest passed."