@tduncan / Nvidia-Optimization-Stack-VLLM Mirror · read-only / commits / 32baf1d036
Fork 0

A high-throughput and memory-efficient inference and serving engine for LLMs

Mirrored from https://github.com/tduncan-lum/Nvidia-Optimization-Stack---VLLM.git

Synced Nov 14, 05:30 UTC

[Docs] Clean up the contributing README (#25099)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>

Harry Mellor committed Sep 18, 2025 at 05:05 UTC 32baf1d03685ead1f5946f867e4ca16007bd10b5
3 files changed +77 -67
docs/contributing/README.md
+75 -66
@@ -26,113 +26,123 @@ See <gh-file:LICENSE>.
26
27 ## Developing
28
29 ---8<-- "docs/getting_started/installation/python_env_setup.inc.md"
30 -
31 -Depending on the kind of development you'd like to do (e.g. Python, CUDA), you can choose to build vLLM with or without compilation.
32 -Check out the [building from source][build-from-source] documentation for details.
29 +The first step of contributing to vLLM is to clone the GitHub repository:
30
34 -For an optimized workflow when iterating on C++/CUDA kernels, see the [Incremental Compilation Workflow](./incremental_build.md) for recommendations.
31 +```bash
32 +git clone https://github.com/vllm-project/vllm.git
33 +cd vllm
34 +```
35
36 -### Building the docs with MkDocs
36 +Then, configure your Python virtual environment.
37
38 -#### Introduction to MkDocs
38 +--8<-- "docs/getting_started/installation/python_env_setup.inc.md"
39
40 -[MkDocs](https://github.com/mkdocs/mkdocs) is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.
40 +If you are only developing vLLM's Python code, install vLLM using:
41
42 -#### Install MkDocs and Plugins
42 +```bash
43 +VLLM_USE_PRECOMPILED=1 uv pip install -e .
44 +```
45
44 -Install MkDocs along with the [plugins](https://github.com/vllm-project/vllm/blob/main/mkdocs.yaml) used in the vLLM documentation, as well as required dependencies:
46 +If you are developing vLLM's Python and CUDA/C++ code, install vLLM using:
47
48 ```bash
47 -uv pip install -r requirements/docs.txt
49 +uv pip install -e .
50 ```
51
50 -!!! note
51 - Ensure that your Python version is compatible with the plugins (e.g., `mkdocs-awesome-nav` requires Python 3.10+)
52 +For more details about installing from source and installing for other hardware, check out the [installation instructions](../getting_started/installation/README.md) for your hardware and head to the "Build wheel from source" section.
53
53 -#### Verify Installation
54 +For an optimized workflow when iterating on C++/CUDA kernels, see the [Incremental Compilation Workflow](./incremental_build.md) for recommendations.
55
55 -Confirm that MkDocs is correctly installed:
56 +!!! tip
57 + vLLM is compatible with Python versions 3.9 to 3.12. However, vLLM's default [Dockerfile](gh-file:docker/Dockerfile) ships with Python 3.12 and tests in CI (except `mypy`) are run with Python 3.12.
58
57 -```bash
58 -mkdocs --version
59 -```
59 + Therefore, we recommend developing with Python 3.12 to minimise the chance of your local environment clashing with our CI environment.
60
61 -Example output:
61 +### Linting
62
63 -```console
64 -mkdocs, version 1.6.1 from /opt/miniconda3/envs/mkdoc/lib/python3.10/site-packages/mkdocs (Python 3.10)
65 -```
66 -
67 -#### Clone the `vLLM` repository
63 +vLLM uses `pre-commit` to lint and format the codebase. See <https://pre-commit.com/#usage> if `pre-commit` is new to you. Setting up `pre-commit` is as easy as:
64
65 ```bash
70 -git clone https://github.com/vllm-project/vllm.git
71 -cd vllm
66 +uv pip install pre-commit
67 +pre-commit install
68 ```
69
74 -#### Start the Development Server
70 +vLLM's `pre-commit` hooks will now run automatically every time you commit.
71
76 -MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` configuration file, and then start the server by running the `mkdocs serve` command:
72 +!!! tip "Tips"
73 + You can manually run the `pre-commit` hooks using:
74
78 -```bash
79 -mkdocs serve
80 -```
75 + ```bash
76 + pre-commit run # runs on staged files
77 + pre-commit run -a # runs on all files (short for --all-files)
78 + ```
79
82 -Example output:
80 + ---
81
84 -```console
85 -INFO - Documentation built in 106.83 seconds
86 -INFO - [22:02:02] Watching paths for changes: 'docs', 'mkdocs.yaml'
87 -INFO - [22:02:02] Serving on http://127.0.0.1:8000/
88 -```
82 + Some `pre-commit` hooks only run in CI. If you need to, you can run them locally with:
83
90 -#### View in Your Browser
84 + ```bash
85 + pre-commit run --hook-stage manual markdownlint
86 + pre-commit run --hook-stage manual mypy-3.9
87 + ```
88
92 -Open up [http://127.0.0.1:8000/](http://127.0.0.1:8000/) in your browser to see a live preview:.
89 +### Documentation
90
94 -#### Learn More
91 +MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file, <gh-file:mkdocs.yaml>.
92
96 -For additional features and advanced configurations, refer to the official [MkDocs Documentation](https://www.mkdocs.org/).
93 +Get started with:
94
98 -## Testing
95 +```bash
96 +uv pip install -r requirements/docs.txt
97 +```
98
100 -??? console "Commands"
99 +!!! tip
100 + Ensure that your Python version is compatible with the plugins
101 + (e.g., `mkdocs-awesome-nav` requires Python 3.10+)
102
102 - ```bash
103 - # These commands are only for Nvidia CUDA platforms.
104 - uv pip install -r requirements/common.txt -r requirements/dev.txt --torch-backend=auto
103 +MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it.
104 +From the root of the repository, run:
105
106 - # Linting, formatting and static type checking
107 - pre-commit install
106 +```bash
107 +mkdocs serve # with API ref (~10 minutes)
108 +API_AUTONAV_EXCLUDE=vllm mkdocs serve # API ref off (~15 seconds)
109 +```
110
109 - # You can manually run pre-commit with
110 - pre-commit run --all-files --show-diff-on-failure
111 +Once you see `Serving on http://127.0.0.1:8000/` in the logs, the live preview is ready!
112 +Open <http://127.0.0.1:8000/> in your browser to see it.
113
112 - # To manually run something from CI that does not run
113 - # locally by default, you can run:
114 - pre-commit run mypy-3.9 --hook-stage manual --all-files
114 +For additional features and advanced configurations, refer to the:
115
116 - # Unit tests
117 - pytest tests/
116 +- [MkDocs documentation](https://www.mkdocs.org/)
117 +- [Material for MkDocs documentation](https://squidfunk.github.io/mkdocs-material/) (the MkDocs theme we use)
118
119 - # Run tests for a single test file with detailed output
120 - pytest -s -v tests/test_logger.py
121 - ```
119 +### Testing
120
123 -!!! tip
124 - Since the <gh-file:docker/Dockerfile> ships with Python 3.12, all tests in CI (except `mypy`) are run with Python 3.12.
121 +vLLM uses `pytest` to test the codebase.
122
126 - Therefore, we recommend developing with Python 3.12 to minimise the chance of your local environment clashing with our CI environment.
123 +```bash
124 +# Install the test dependencies used in CI (CUDA only)
125 +uv pip install -r requirements/common.txt -r requirements/dev.txt --torch-backend=auto
126 +
127 +# Install some common test dependencies (hardware agnostic)
128 +uv pip install pytest pytest-asyncio
129 +
130 +# Run all tests
131 +pytest tests/
132
128 -!!! note "Install python3-dev if Python.h is missing"
133 +# Run tests for a single test file with detailed output
134 +pytest -s -v tests/test_logger.py
135 +```
136 +
137 +!!! tip "Install python3-dev if Python.h is missing"
138 If any of the above commands fails with `Python.h: No such file or directory`, install
139 `python3-dev` with `sudo apt install python3-dev`.
140
132 -!!! note
141 +!!! warning "Warnings"
142 Currently, the repository is not fully checked by `mypy`.
143
135 -!!! note
144 + ---
145 +
146 Currently, not all unit tests pass when run on CPU platforms. If you don't have access to a GPU
147 platform to run unit tests locally, rely on the continuous integration system to run the tests for
148 now.
@@ -194,8 +204,7 @@ appropriately to indicate the type of change. Please use one of the following:
204 The PR needs to meet the following code quality standards:
205
206 - We adhere to [Google Python style guide](https://google.github.io/styleguide/pyguide.html) and [Google C++ style guide](https://google.github.io/styleguide/cppguide.html).
197 -- Pass all linter checks. Please use `pre-commit` to format your code. See
198 - <https://pre-commit.com/#usage> if `pre-commit` is new to you.
207 +- Pass all linter checks.
208 - The code needs to be well-documented to ensure future contributors can easily
209 understand the code.
210 - Include sufficient tests to ensure the project stays correct and robust. This
docs/getting_started/installation/python_env_setup.inc.md
+1 -1
@@ -1,4 +1,4 @@
1 -It's recommended to use [uv](https://docs.astral.sh/uv/), a very fast Python environment manager, to create and manage Python environments. Please follow the [documentation](https://docs.astral.sh/uv/#getting-started) to install `uv`. After installing `uv`, you can create a new Python environment and install vLLM using the following commands:
1 +It's recommended to use [uv](https://docs.astral.sh/uv/), a very fast Python environment manager, to create and manage Python environments. Please follow the [documentation](https://docs.astral.sh/uv/#getting-started) to install `uv`. After installing `uv`, you can create a new Python environment using the following commands:
2
3 ```bash
4 uv venv --python 3.12 --seed
mkdocs.yaml
+1
@@ -79,6 +79,7 @@ plugins:
79 - "re:vllm\\._.*" # Internal modules
80 - "vllm.third_party"
81 - "vllm.vllm_flash_attn"
82 + - !ENV [API_AUTONAV_EXCLUDE, ""]
83 - mkdocstrings:
84 handlers:
85 python: