conf.py 8.32 KB
Newer Older
1
2
# SPDX-License-Identifier: Apache-2.0

Woosuk Kwon's avatar
Woosuk Kwon committed
3
4
5
6
7
8
9
10
11
12
13
14
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# 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.

15
import datetime
16
import logging
17
import os
18
import re
19
import sys
20
from pathlib import Path
21

22
import requests
23
24

logger = logging.getLogger(__name__)
25
26
REPO_ROOT = Path(__file__).resolve().parent.parent.parent
sys.path.append(os.path.abspath(REPO_ROOT))
Woosuk Kwon's avatar
Woosuk Kwon committed
27
28
29

# -- Project information -----------------------------------------------------

Woosuk Kwon's avatar
Woosuk Kwon committed
30
project = 'vLLM'
31
copyright = f'{datetime.datetime.now().year}, vLLM Team'
Woosuk Kwon's avatar
Woosuk Kwon committed
32
author = 'the vLLM Team'
Woosuk Kwon's avatar
Woosuk Kwon committed
33
34
35
36
37
38
39
40

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    "sphinx.ext.napoleon",
41
    "sphinx.ext.linkcode",
Woosuk Kwon's avatar
Woosuk Kwon committed
42
43
    "sphinx.ext.intersphinx",
    "sphinx_copybutton",
44
    "autodoc2",
45
46
    "myst_parser",
    "sphinxarg.ext",
47
    "sphinx_design",
48
49
50
51
    "sphinx_togglebutton",
]
myst_enable_extensions = [
    "colon_fence",
52
    "fieldlist",
Woosuk Kwon's avatar
Woosuk Kwon committed
53
]
54
55
56
57
58
59
60
61
62
63
64
autodoc2_packages = [
    {
        "path": "../../vllm",
        "exclude_dirs": ["__pycache__", "third_party"],
    },
]
autodoc2_output_dir = "api"
autodoc2_render_plugin = "myst"
autodoc2_hidden_objects = ["dunder", "private", "inherited"]
autodoc2_sort_names = True
autodoc2_index_template = None
Woosuk Kwon's avatar
Woosuk Kwon committed
65
66
67
68
69
70
71

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
72
exclude_patterns: list[str] = ["**/*.template.md", "**/*.inc.md"]
Woosuk Kwon's avatar
Woosuk Kwon committed
73
74
75
76
77
78
79
80
81
82
83
84

# Exclude the prompt "$" when copying code
copybutton_prompt_text = r"\$ "
copybutton_prompt_is_regexp = True

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_title = project
html_theme = 'sphinx_book_theme'
85
html_logo = 'assets/logos/vllm-logo-text-light.png'
Harry Mellor's avatar
Harry Mellor committed
86
html_favicon = 'assets/logos/vllm-logo-only-light.ico'
Woosuk Kwon's avatar
Woosuk Kwon committed
87
88
html_theme_options = {
    'path_to_docs': 'docs/source',
89
    'repository_url': 'https://github.com/vllm-project/vllm',
Woosuk Kwon's avatar
Woosuk Kwon committed
90
    'use_repository_button': True,
91
    'use_edit_page_button': True,
92
93
94
95
96
    # Prevents the full API being added to the left sidebar of every page.
    # Reduces build time by 2.5x and reduces build size from ~225MB to ~95MB.
    'collapse_navbar': True,
    # Makes API visible in the right sidebar on API reference pages.
    'show_toc_level': 3,
Woosuk Kwon's avatar
Woosuk Kwon committed
97
}
98
99
100
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
101
102
html_static_path = ["_static"]
html_js_files = ["custom.js"]
103
html_css_files = ["custom.css"]
Woosuk Kwon's avatar
Woosuk Kwon committed
104

105
myst_heading_anchors = 2
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
myst_url_schemes = {
    'http': None,
    'https': None,
    'mailto': None,
    'ftp': None,
    "gh-issue": {
        "url":
        "https://github.com/vllm-project/vllm/issues/{{path}}#{{fragment}}",
        "title": "Issue #{{path}}",
        "classes": ["github"],
    },
    "gh-pr": {
        "url":
        "https://github.com/vllm-project/vllm/pull/{{path}}#{{fragment}}",
        "title": "Pull Request #{{path}}",
        "classes": ["github"],
    },
123
    "gh-project": {
124
        "url": "https://github.com/orgs/vllm-project/projects/{{path}}",
125
126
127
        "title": "Project #{{path}}",
        "classes": ["github"],
    },
128
129
130
131
132
133
134
135
136
137
138
139
    "gh-dir": {
        "url": "https://github.com/vllm-project/vllm/tree/main/{{path}}",
        "title": "{{path}}",
        "classes": ["github"],
    },
    "gh-file": {
        "url": "https://github.com/vllm-project/vllm/blob/main/{{path}}",
        "title": "{{path}}",
        "classes": ["github"],
    },
}

140
141
142
143
144
145
# see https://docs.readthedocs.io/en/stable/reference/environment-variables.html # noqa
READTHEDOCS_VERSION_TYPE = os.environ.get('READTHEDOCS_VERSION_TYPE')
if READTHEDOCS_VERSION_TYPE == "tag":
    # remove the warning banner if the version is a tagged release
    header_file = os.path.join(os.path.dirname(__file__),
                               "_templates/sections/header.html")
146
147
148
149
    # The file might be removed already if the build is triggered multiple times
    # (readthedocs build both HTML and PDF versions separately)
    if os.path.exists(header_file):
        os.remove(header_file)
150

151
152
153
154
155
156
157

# Generate additional rst documentation here.
def setup(app):
    from docs.source.generate_examples import generate_examples
    generate_examples()


158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
_cached_base: str = ""
_cached_branch: str = ""


def get_repo_base_and_branch(pr_number):
    global _cached_base, _cached_branch
    if _cached_base and _cached_branch:
        return _cached_base, _cached_branch

    url = f"https://api.github.com/repos/vllm-project/vllm/pulls/{pr_number}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        _cached_base = data['head']['repo']['full_name']
        _cached_branch = data['head']['ref']
        return _cached_base, _cached_branch
    else:
        logger.error("Failed to fetch PR details: %s", response)
        return None, None


def linkcode_resolve(domain, info):
    if domain != 'py':
        return None
    if not info['module']:
        return None
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

    # Get path from module name
    file = Path(f"{info['module'].replace('.', '/')}.py")
    path = REPO_ROOT / file
    if not path.exists():
        path = REPO_ROOT / file.with_suffix("") / "__init__.py"
    if not path.exists():
        return None

    # Get the line number of the object
    with open(path) as f:
        lines = f.readlines()
    name = info['fullname'].split(".")[-1]
    pattern = fr"^( {{4}})*((def|class) )?{name}\b.*"
    for lineno, line in enumerate(lines, 1):
        if not line or line.startswith("#"):
            continue
        if re.match(pattern, line):
            break

    # If the line number is not found, return None
    if lineno == len(lines):
        return None

    # If the line number is found, create the URL
    filename = path.relative_to(REPO_ROOT)
    if "checkouts" in path.parts:
211
        # a PR build on readthedocs
212
        pr_number = REPO_ROOT.name
213
214
215
216
217
218
219
        base, branch = get_repo_base_and_branch(pr_number)
        if base and branch:
            return f"https://github.com/{base}/blob/{branch}/{filename}#L{lineno}"
    # Otherwise, link to the source file on the main branch
    return f"https://github.com/vllm-project/vllm/blob/main/{filename}#L{lineno}"


220
# Mock out external dependencies here, otherwise sphinx-argparse won't work.
221
autodoc_mock_imports = [
222
223
224
225
226
227
    "huggingface_hub",
    "pydantic",
    "zmq",
    "cloudpickle",
    "aiohttp",
    "starlette",
228
    "blake3",
229
    "cpuinfo",
230
231
232
    "transformers",
    "psutil",
    "vllm._C",
233
    "PIL",
234
235
    "numpy",
    "tqdm",
236
237
238
239
240
241
    # The mocks below are required by
    # docs/source/serving/openai_compatible_server.md's
    # vllm.entrypoints.openai.cli_args
    "openai",
    "fastapi",
    "partial_json_parser",
242
243
244
245
246
]

for mock_target in autodoc_mock_imports:
    if mock_target in sys.modules:
        logger.info(
247
            "Potentially problematic mock target (%s) found; "
248
            "autodoc_mock_imports cannot mock modules that have already "
249
250
            "been loaded into sys.modules when the sphinx build starts.",
            mock_target)
251

252
intersphinx_mapping = {
253
254
255
    "python": ("https://docs.python.org/3", None),
    "typing_extensions":
    ("https://typing-extensions.readthedocs.io/en/latest", None),
256
    "aiohttp": ("https://docs.aiohttp.org/en/stable", None),
257
258
259
260
    "pillow": ("https://pillow.readthedocs.io/en/stable", None),
    "numpy": ("https://numpy.org/doc/stable", None),
    "torch": ("https://pytorch.org/docs/stable", None),
    "psutil": ("https://psutil.readthedocs.io/en/stable", None),
261
262
}

263
navigation_with_keys = False